Deploy Hermes Declaratively with Nix and NixOS

Hermes ships a Nix flake and NixOS module for reproducible deployment. Nix and NixOS are Tier 2 platforms, so operators should value repeatability without assuming the same support level as the standard installation path.

Official documentation: https://hermes-agent.nousresearch.com/docs/getting-started/nix-setup

Choose the deployment mode deliberately

For ordinary Nix users, nix run or nix profile install changes only installation; normal Hermes setup follows. The NixOS module moves configuration into configuration.nix, manages the service with systemd, and expects secrets through a protected environment file or a system such as sops-nix or agenix. Container mode trades some immutability for persistent package installation inside an isolated Ubuntu environment.

Keep state ownership unambiguous

When the system service and interactive CLI should share sessions, skills, and cron state, configure the same HERMES_HOME path intentionally. An interactive shell silently creating a separate ~/.hermes tree can look like lost configuration even though two independent instances exist.

Operational checklist

Choose profile install, native module, or container mode.
Document the state directory and service user.
Keep provider secrets outside the Nix store.
Select only the dependency groups required.
Rebuild declaratively after configuration changes.
Verify service status and journal logs.
Back up state before changing container identity or volumes.

Common pitfalls

Writing secrets into world-readable Nix expressions.
Using CLI config writes against Nix-managed configuration.
Running a host CLI against a different Hermes home.
Assuming container package changes survive a recreated writable layer.
Treating Tier 2 support as a production guarantee.

Verification steps

Run nixos-rebuild switch or complete the profile install.
Check systemctl status hermes-agent in module mode.
Inspect journalctl -u hermes-agent for startup errors.
Run hermes version and inspect the effective config.
Confirm the intended state directory is used.
Restart the service and repeat one harmless agent task.

A reliable Hermes workflow is defined by observable behavior, bounded authority, and repeatable verification—not by configuration alone.