SSOT role (desktop-nixos RFC 2026-06-29): owns hermes-agent software (Nix package + NixOS module). Consumed by desktop-nixos as a pinned flake input.
Third-party Nix flake packaging NousResearch/hermes-agent for NixOS. Vendor-neutral defaults, four isolation modes, hourly upstream tracker.
Attribution.
hermes-agentis built and maintained by the NousResearch team. This repository is a community-maintained Nix wrapper — it does not modify the agent, does not represent NousResearch, and is not endorsed by them. Report bugs in the agent itself toNousResearch/hermes-agent; report bugs in the Nix packaging or NixOS module to this repository.
nix run "https://flakehub.com/f/ErikBPF/hermes-flake/*" -- --version
nix run github:ErikBPF/hermes-flake -- --version
This flake tracks upstream NousResearch/hermes-agent releases with an
automated update PR. Successful main builds publish to FlakeHub.
- Rolling:
https://flakehub.com/f/ErikBPF/hermes-flake/*follows every published main build. Fastest path. - Version pin: pin an exact FlakeHub release or git tag for reproducible services. Best default for production hosts.
- Commit pin: pin an exact commit and build locally when you want the smallest trust surface.
Using a binary cache adds trust in that cache. Building locally avoids that extra trust layer at the cost of slower upgrades.
| Output | What |
|---|---|
packages.<sys>.hermes-agent |
Base — pick extras via .withExtras [ ... ] |
packages.<sys>.hermes-agent-full |
Every declared extra |
nixosModules.default |
System service, bare-metal |
nixosModules.hermes-agent-container |
systemd-nspawn isolation |
nixosModules.hermes-agent-podman |
OCI container, nix-built image (podman or docker) |
nixosModules.hermes-agent-oci |
OCI container, official upstream image — recommended for production |
nixosModules.hermes-agent-microvm |
KVM-isolated guest |
homeManagerModules.default |
Per-user install |
overlays.default |
pkgs.hermes-agent everywhere |
{
inputs.hermes-flake.url = "https://flakehub.com/f/ErikBPF/hermes-flake/*";
outputs = { nixpkgs, hermes-flake, sops-nix, ... }: {
nixosConfigurations.host = nixpkgs.lib.nixosSystem {
modules = [
sops-nix.nixosModules.sops
hermes-flake.nixosModules.default
({ config, ... }: {
sops.secrets."hermes-agent/env" = {
sopsFile = ./secrets/hermes.env.sops;
format = "dotenv";
owner = "hermes";
mode = "0440";
};
services.hermes-agent = {
enable = true;
environmentFile = config.sops.secrets."hermes-agent/env".path;
extras = [ "voice" "anthropic" "mcp" ];
telegramAllowedUsers = [ 123456789 ];
};
})
];
};
};
}
Full example: example/configuration.nix. Container variant: example/container.nix.
hermes-agent ships base only. Pick optional extras at build time:
# discover
nix eval github:ErikBPF/hermes-flake#hermes-agent.availableExtras
# build with specific extras
nix build --impure --expr \
'(builtins.getFlake "github:ErikBPF/hermes-flake").packages.x86_64-linux.hermes-agent.withExtras [ "voice" "anthropic" ]'
# or via module option
services.hermes-agent.extras = [ "voice" "anthropic" "mcp" ];
Unknown extra names error at eval time. See docs/ENV_VARS.md for full reference.
High-level groups (canonical reference is docs/ENV_VARS.md):
- Core:
enable,package,extras,user/group,dataDir,environmentFile,configFile,settings,soulFile,profile - API server (8642):
openBindAddress,apiPort,apiServerCorsOrigins,apiServerModelName,maxIterations - Webhook gateway (8644):
webhookPort+ routes viasettings.platforms.webhook.extra.routes(docs/WEBHOOK_ROUTES.md) - Telegram:
telegramAllowedUsers,telegramAllowedChats,telegramAllowedTopics - Dashboard (9119, off):
enableDashboard,dashboardHost,dashboardPort - Model backend:
openaiBaseUrl - systemd:
memoryMax,cpuQuota,openFirewall,extraServiceDeps. Baseline process safety (NoNewPrivileges,PrivateTmp,ProtectSystem=strict,ProtectHome=read-only,ReadWritePaths=[dataDir]) always applied. Kernel-level hardening is not prescribed — apply via standardsystemd.services.hermes-agent.serviceConfigoverride. - Healthcheck:
enableHealthcheck,healthcheckInterval
Inspect interactively:
nix repl
> :lf .
> nixosModules.default { config = {}; lib = (import <nixpkgs> {}).lib; pkgs = (import <nixpkgs> {}); }.options.services.hermes-agent
- Lazy-installed deps. Hermes installs
python-telegram-bot[webhooks],discord.py[voice], ripgrep, ffmpeg, node, browsers on first use inside$HERMES_HOME(=dataDir).ProtectSystem=strict+ReadWritePaths=[dataDir]allows this;ProtectHome=read-only+HERMES_HOME=dataDirkeeps writes inside mutable storage. - Playwright/Chromium. First browser-tool invocation downloads ~150 MB into
dataDir. - Single instance per dataDir.
gateway run --replaceensures only one running gateway. Don't run the systemd service AND a CLI session against the same dataDir.
nix develop # dev shell
just # list recipes
just build # base
just build-extras "voice anthropic mcp" # custom
just check / check-full / check-vm
just update-check / update / update-to VERSION
just extras / fmt / lint
docs/ENV_VARS.md— upstream-audited env var truth tabledocs/ISOLATION.md— bare-metal / nspawn / podman / microvm trade-offsdocs/CLIENT.md— client patterns (local CLI / delegated / web / messaging / ACP)docs/SOPS.md— sops-nix integration recipedocs/WEBHOOK_ROUTES.md— per-route HMAC patterndocs/STATE.md— what persists indataDir, backup proceduredocs/MIGRATION.md— Docker → NixOS migrationdocs/RELEASING.md— maintainer release flowCONTRIBUTING.md— contributor guideSECURITY.md— vuln reporting + threat modelCHANGELOG.md— release notesNOTICE— upstream attribution
nix, nix-flake, nixos, nixos-module, hermes-agent, nousresearch, llm, ai-agent, anthropic, openrouter, litellm, sops-nix, microvm, systemd-nspawn, podman, oci-container, uv2nix, pyproject-nix