feat: nix flake — uv2nix build, NixOS module, persistent container mode by alt-glitch · Pull Request #20 · NousResearch/hermes-agent

alt-glitch · 2026-02-08T18:24:02Z

Summary

nix build produces a fully self-contained package — all Python deps are Nix derivations via uv2nix, no runtime pip
nix develop provides a dev shell with Python 3.11, uv, node, ripgrep, git, ffmpeg
NixOS module with two deployment modes: native systemd service (hardened) or persistent OCI container (Ubuntu 24.04 base, writable layer survives restarts and rebuilds)
Managed mode guards block hermes setup, config set, gateway install/uninstall when running under the NixOS module
CI workflow validates Nix build on linux x86 with every PR (macOS skipped — onnxruntime wheel missing on aarch64-darwin)

What changed

flake.nix — flake entrypoint wiring all Nix outputs (package, dev shell, NixOS module, checks)
nix/python.nix — uv2nix Python 3.11 venv derivation
nix/packages.nix — wraps uv2nix venv entry points (hermes, hermes-agent, hermes-acp) with runtime PATH (git, node, ripgrep, ffmpeg, openssh). Bundles skills/ into share/hermes-agent/skills (filtered to exclude index-cache/) and sets HERMES_BUNDLED_SKILLS env var so skills_sync finds them in the Nix store
nix/nixosModules.nix — NixOS module with full declarative config surface:
- Mode A (native): systemd service with ProtectSystem=strict, NoNewPrivileges, secret env files
- Mode B (container): persistent Ubuntu container with /nix/store bind-mounted read-only. Runs as --user UID:GID matching configured service user. Hermes runs via a current-package symlink updated on rebuild. Identity hash triggers container recreation only on image/env/volume changes — apt/pip/npm installs persist across restarts, rebuilds, reboots, and GC
- Declarative settings (deep-merged via nix/configMergeScript.nix, rendered as config.yaml), documents, mcpServers, sops-nix/agenix-compatible environmentFiles, OAuth authFile seeding
nix/config-keys.json — exhaustive list of valid config keys for build-time validation of declarative settings
nix/checks.nix — build-time verification: binary existence, entry point sync with pyproject.toml, CLI subcommands, HERMES_MANAGED guard coverage, bundled skills presence
nix/devShell.nix — stamp-file-optimized dev shell
.github/workflows/nix.yml — CI workflow running nix flake check + nix build on linux x86 with DeterminateSystems magic-nix-cache
tools/skills_sync.py — _get_bundled_dir() checks HERMES_BUNDLED_SKILLS env var before falling back to relative path
tests/tools/test_skills_sync.py — tests for HERMES_BUNDLED_SKILLS env var override
hermes_cli/config.py — is_managed() + managed_error() guards on config mutation paths; fix Path type mismatch in os.getenv default
hermes_cli/gateway.py — guards on gateway setup, install, uninstall
hermes_cli/setup.py — guard on setup wizard
website/docs/getting-started/nix-setup.md — full setup guide: options reference, container architecture, secrets management, persistence model, troubleshooting

Container persistence model

Event	Container recreated?	State (`/data`)	Writable layer (`apt`/`pip`/`npm`)
`systemctl restart`	No	Persists	Persists
`nixos-rebuild switch`	No (symlink update)	Persists	Persists
Host reboot	No	Persists	Persists
`nix-collect-garbage`	No (GC root)	Persists	Persists
Image/env/volume change	Yes	Persists	Lost

Test plan

docs/nixos-setup.md

nix/devShell.nix

nix/packages.nix

0xrsydn · 2026-03-15T23:25:57Z

hi, is there any plan to do native nix supports sooner? I like to try this on my own nixos server, thank u 🙏

alt-glitch · 2026-03-16T05:56:46Z

hey @0xrsydn !
thanks for showing interest. i'll try to push some updates here and get this out soon.
@arilotter will review but would appreciate your feedback / review as well as a fellow nixos user :)

0xrsydn · 2026-03-16T11:38:40Z

hey @0xrsydn !

thanks for showing interest. i'll try to push some updates here and get this out soon.

@arilotter will review but would appreciate your feedback / review as well as a fellow nixos user :)

actually i have build my own hermes flake for now, but id love to try the native support and give some feedbacks if needed later once its updated, thank you very much 🙏

0xrsydn · 2026-03-17T15:30:53Z

btw i also have built my own package here and have been working great, deployed on my nixos server and connected to telegram. would love for more suggestion or maybe easier and flexible approach to use hermes agent flake later on

sylvesterroos · 2026-03-20T18:33:45Z

Does $HERMES_HOME need to be set using this module? I'm trying it out, and the first run's setup creates a .hermes dir in my home when I would assume that the setup either needs to get skipped or it needs to place the settings in /var/lib/hermes/.hermes

and it might be worth investigating if the container can be recreated automatically if the eg environment file changes. I kept trying to figure out why my new env vars werent being applied but apparently i had to manually recreate the container (by performing the steps in the markdown file)

alt-glitch · 2026-03-23T06:55:38Z

hey @sylvesterroos!
thanks for the comments

The module now sets environment.variables.HERMES_HOME system-wide when addToSystemPackages = true, so running hermes in your shell shares state with the gateway service instead of creating a separate ~/.hermes.

As for the secrets, they are no long injected into the container but read from $HERMES_HOME/.env. So changing env vars requires a systemctl restart hermes-agent to pick up the new values. no container recreation needed

lattwood · 2026-03-23T19:24:17Z

@alt-glitch is what's remaining the stuff on your test plan?

edit: ie, does helping with testing get this closer to merged

alt-glitch · 2026-03-23T21:19:32Z

@lattwood -- yes!
if you can run this branch in the config you want (container or local), and gimme a heads up on any bugs, that'd be really helpful.

i'm pushing a couple more fixes right now.

github-actions · 2026-03-24T16:52:35Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

…s, checks - Replace homeModules.nix with nixosModules.nix (two deployment modes) - Mode A (native): hardened systemd service with ProtectSystem=strict - Mode B (container): persistent Ubuntu container with /nix/store bind-mount, identity-hash-based recreation, GC root protection, symlink-based updates - Add HERMES_MANAGED guards blocking CLI config mutation (config set, setup, gateway install/uninstall) when running under NixOS module - Add nix/checks.nix with build-time verification (binary, CLI, managed guard) - Remove container.nix (no Nix-built OCI image; pulls ubuntu:24.04 at runtime) - Simplify packages.nix (drop fetchFromGitHub submodules, PYTHONPATH wrappers) - Rewrite docs/nixos-setup.md with full options reference, container architecture, secrets management, and troubleshooting guide Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- GitHub Actions workflow for nix flake check + build on linux/macOS - Entry point sync check to catch pyproject.toml drift - Expanded managed-guard check to cover config edit - Wrap hermes-acp binary in Nix package - Fix Path type mismatch in is_managed()

…ning Container was running as non-root via --user, which broke apt/pip installs and caused crashes when $HOME didn't exist. Replace --user with a Nix-built entrypoint script that provisions the hermes user, sudo (NOPASSWD), and /home/hermes inside the container on first boot, then drops privileges via setpriv. Writable layer persists so setup only runs once. Also expands MCP server options to support HTTP transport and sampling. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Container mode now bind-mounts ${stateDir}/home to /home/hermes so the agent's home directory survives container recreation. Previously it lived in the writable layer and was lost on image/volume/options changes. Also passes MESSAGING_CWD to the container so the agent finds its workspace and documents, matching native mode behavior. Other changes: - Extract containerDataDir/containerHomeDir bindings (no more magic strings) - Fix entrypoint chown to run unconditionally (volume mounts always exist) - Add schema field to container identity hash for auto-recreation - Add idempotency test (Scenario G) to config-roundtrip check

Add comprehensive Nix documentation to the Docusaurus site at website/docs/getting-started/nix-setup.md, covering nix run/profile install, NixOS module (native + container modes), declarative settings, secrets management, MCP servers, managed mode, container architecture, dev shell, flake checks, and full options reference. - Register nix-setup in sidebar after installation page - Add Nix callout tip to installation.md linking to new guide - Add canonical version pointer in docs/nixos-setup.md

github-actions · 2026-03-25T06:03:43Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

Backfill missing details (restart/restartSec in full example, gateway.pid, 0750 permissions, docker inspect commands) into the canonical website/docs/getting-started/nix-setup.md and delete the old standalone file.

github-actions · 2026-03-25T06:13:18Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

…eys.json New keys were added to DEFAULT_CONFIG on main, causing the config-drift check to fail in CI.

github-actions · 2026-03-25T06:17:42Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

The full Python venv includes onnxruntime (via faster-whisper/STT) which lacks a compatible uv2nix wheel on aarch64-darwin. Gate all checks behind stdenv.hostPlatform.isLinux. The package and devShell still evaluate on macOS.

github-actions · 2026-03-25T06:33:03Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

onnxruntime (transitive dep via faster-whisper) lacks a compatible uv2nix wheel on aarch64-darwin. Run full checks and build on Linux only; macOS CI verifies the flake evaluates without building.

github-actions · 2026-03-25T06:37:24Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

The container identity hash included the entrypoint's Nix store path, which changes on every nixpkgs update (due to runtimeShell/stdenv input-addressing). This caused false-positive identity mismatches, triggering container recreation and losing the persistent writable layer. - Use stable symlink (current-entrypoint) like current-package already does - Remove entrypoint from identity hash (only image/volumes/options matter) - Add GC root for entrypoint so nix-collect-garbage doesn't break it - Remove global HERMES_HOME env var from addToSystemPackages (conflicted with interactive CLI use, service already sets its own)

github-actions · 2026-03-25T18:19:03Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

…de (NousResearch#20) * feat: nix flake, uv2nix build, dev shell and home manager * fixed nix run, updated docs for setup * feat(nix): NixOS module with persistent container mode, managed guards, checks - Replace homeModules.nix with nixosModules.nix (two deployment modes) - Mode A (native): hardened systemd service with ProtectSystem=strict - Mode B (container): persistent Ubuntu container with /nix/store bind-mount, identity-hash-based recreation, GC root protection, symlink-based updates - Add HERMES_MANAGED guards blocking CLI config mutation (config set, setup, gateway install/uninstall) when running under NixOS module - Add nix/checks.nix with build-time verification (binary, CLI, managed guard) - Remove container.nix (no Nix-built OCI image; pulls ubuntu:24.04 at runtime) - Simplify packages.nix (drop fetchFromGitHub submodules, PYTHONPATH wrappers) - Rewrite docs/nixos-setup.md with full options reference, container architecture, secrets management, and troubleshooting guide Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Update config.py * feat(nix): add CI workflow and enhanced build checks - GitHub Actions workflow for nix flake check + build on linux/macOS - Entry point sync check to catch pyproject.toml drift - Expanded managed-guard check to cover config edit - Wrap hermes-acp binary in Nix package - Fix Path type mismatch in is_managed() * Update MCP server package name; bundled skills support * fix reading .env. instead have container user a common mounted .env file * feat(nix): container entrypoint with privilege drop and sudo provisioning Container was running as non-root via --user, which broke apt/pip installs and caused crashes when $HOME didn't exist. Replace --user with a Nix-built entrypoint script that provisions the hermes user, sudo (NOPASSWD), and /home/hermes inside the container on first boot, then drops privileges via setpriv. Writable layer persists so setup only runs once. Also expands MCP server options to support HTTP transport and sampling. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix group and user creation in container mode * feat(nix): persistent /home/hermes and MESSAGING_CWD in container mode Container mode now bind-mounts ${stateDir}/home to /home/hermes so the agent's home directory survives container recreation. Previously it lived in the writable layer and was lost on image/volume/options changes. Also passes MESSAGING_CWD to the container so the agent finds its workspace and documents, matching native mode behavior. Other changes: - Extract containerDataDir/containerHomeDir bindings (no more magic strings) - Fix entrypoint chown to run unconditionally (volume mounts always exist) - Add schema field to container identity hash for auto-recreation - Add idempotency test (Scenario G) to config-roundtrip check * docs: add Nix & NixOS setup guide to docs site Add comprehensive Nix documentation to the Docusaurus site at website/docs/getting-started/nix-setup.md, covering nix run/profile install, NixOS module (native + container modes), declarative settings, secrets management, MCP servers, managed mode, container architecture, dev shell, flake checks, and full options reference. - Register nix-setup in sidebar after installation page - Add Nix callout tip to installation.md linking to new guide - Add canonical version pointer in docs/nixos-setup.md * docs: remove docs/nixos-setup.md, consolidate into website docs Backfill missing details (restart/restartSec in full example, gateway.pid, 0750 permissions, docker inspect commands) into the canonical website/docs/getting-started/nix-setup.md and delete the old standalone file. * fix(nix): add compression.protect_last_n and target_ratio to config-keys.json New keys were added to DEFAULT_CONFIG on main, causing the config-drift check to fail in CI. * fix(nix): skip checks on aarch64-darwin (onnxruntime wheel missing) The full Python venv includes onnxruntime (via faster-whisper/STT) which lacks a compatible uv2nix wheel on aarch64-darwin. Gate all checks behind stdenv.hostPlatform.isLinux. The package and devShell still evaluate on macOS. * fix(nix): skip flake check and build on macOS CI onnxruntime (transitive dep via faster-whisper) lacks a compatible uv2nix wheel on aarch64-darwin. Run full checks and build on Linux only; macOS CI verifies the flake evaluates without building. * fix(nix): preserve container writable layer across nixos-rebuild The container identity hash included the entrypoint's Nix store path, which changes on every nixpkgs update (due to runtimeShell/stdenv input-addressing). This caused false-positive identity mismatches, triggering container recreation and losing the persistent writable layer. - Use stable symlink (current-entrypoint) like current-package already does - Remove entrypoint from identity hash (only image/volumes/options matter) - Add GC root for entrypoint so nix-collect-garbage doesn't break it - Remove global HERMES_HOME env var from addToSystemPackages (conflicted with interactive CLI use, service already sets its own) --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

alt-glitch force-pushed the sid/nix-flake branch from da9d4bd to 6cd77ba Compare March 9, 2026 14:54

alt-glitch changed the title ~~feat: add nix flake + setup~~ Mar 9, 2026

alt-glitch changed the title ~~feat: nix flake — NixOS module, dev shell, and package~~ Mar 11, 2026

alt-glitch force-pushed the sid/nix-flake branch from 745896e to 73ddcd6 Compare March 11, 2026 11:33

alt-glitch changed the title ~~feat: nix flake — dev shell + home-manager module~~ Mar 11, 2026

alt-glitch changed the base branch from main to fix/packaging-bugs March 11, 2026 11:33

alt-glitch force-pushed the fix/packaging-bugs branch from 986ae3f to 1d4a23f Compare March 11, 2026 11:37

alt-glitch force-pushed the sid/nix-flake branch from 73ddcd6 to dbc490d Compare March 11, 2026 11:40

alt-glitch mentioned this pull request Mar 11, 2026

fix: add missing packages to setuptools config #912

Merged

alt-glitch force-pushed the sid/nix-flake branch from 4942051 to 5776287 Compare March 11, 2026 12:10

alt-glitch marked this pull request as ready for review March 11, 2026 12:11

arilotter reviewed Mar 12, 2026

View reviewed changes

docs/nixos-setup.md Outdated Show resolved Hide resolved

docs/nixos-setup.md Outdated Show resolved Hide resolved

nix/devShell.nix Show resolved Hide resolved

nix/packages.nix Outdated Show resolved Hide resolved

nix/packages.nix Show resolved Hide resolved

alt-glitch marked this pull request as draft March 14, 2026 04:43

alt-glitch force-pushed the sid/nix-flake branch from a06b5dd to 71a3a44 Compare March 19, 2026 10:42

alt-glitch changed the base branch from fix/packaging-bugs to main March 19, 2026 10:44

alt-glitch marked this pull request as ready for review March 19, 2026 10:45

alt-glitch requested a review from arilotter March 19, 2026 10:45

alt-glitch changed the title ~~feat: nix flake — uv2nix build + dev shell + home-manager~~ Mar 19, 2026

alt-glitch force-pushed the sid/nix-flake branch from 20e02c7 to dfa0124 Compare March 24, 2026 16:52

alt-glitch added 2 commits March 25, 2026 11:31

feat: nix flake, uv2nix build, dev shell and home manager

63b583a

fixed nix run, updated docs for setup

1e8fae2

alt-glitch and others added 9 commits March 25, 2026 11:31

Update config.py

8c47575

Update MCP server package name; bundled skills support

76135a8

fix reading .env. instead have container user a common mounted .env file

211bf79

fix group and user creation in container mode

db39702

alt-glitch force-pushed the sid/nix-flake branch from 7740fd0 to ca38a51 Compare March 25, 2026 06:03

docs: remove docs/nixos-setup.md, consolidate into website docs

08c1fea

Backfill missing details (restart/restartSec in full example, gateway.pid, 0750 permissions, docker inspect commands) into the canonical website/docs/getting-started/nix-setup.md and delete the old standalone file.

fix(nix): add compression.protect_last_n and target_ratio to config-k…

bc3686e

…eys.json New keys were added to DEFAULT_CONFIG on main, causing the config-drift check to fail in CI.

fix(nix): skip flake check and build on macOS CI

06ef875

onnxruntime (transitive dep via faster-whisper) lacks a compatible uv2nix wheel on aarch64-darwin. Run full checks and build on Linux only; macOS CI verifies the flake evaluates without building.

alt-glitch merged commit b646190 into main Mar 25, 2026
4 of 5 checks passed

SHL0MS mentioned this pull request Mar 30, 2026

[UX] Argument-level tab completion for /resume, /skin, /personality, etc. #4059

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: nix flake — uv2nix build, NixOS module, persistent container mode#20

feat: nix flake — uv2nix build, NixOS module, persistent container mode#20
alt-glitch merged 16 commits intomainfrom
sid/nix-flake

alt-glitch commented Feb 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

0xrsydn commented Mar 15, 2026

alt-glitch commented Mar 16, 2026

0xrsydn commented Mar 16, 2026

0xrsydn commented Mar 17, 2026

sylvesterroos commented Mar 20, 2026 •

edited

Loading

alt-glitch commented Mar 23, 2026

lattwood commented Mar 23, 2026 •

edited

Loading

alt-glitch commented Mar 23, 2026

github-actions bot commented Mar 24, 2026

github-actions bot commented Mar 25, 2026

github-actions bot commented Mar 25, 2026

github-actions bot commented Mar 25, 2026

github-actions bot commented Mar 25, 2026

github-actions bot commented Mar 25, 2026

github-actions bot commented Mar 25, 2026

Uh oh!

Labels

5 participants

Conversation

alt-glitch commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Container persistence model

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

0xrsydn commented Mar 15, 2026

alt-glitch commented Mar 16, 2026

0xrsydn commented Mar 16, 2026

0xrsydn commented Mar 17, 2026

sylvesterroos commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

alt-glitch commented Mar 23, 2026

lattwood commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

alt-glitch commented Mar 23, 2026

github-actions bot commented Mar 24, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: Install hook files modified

github-actions bot commented Mar 25, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: Install hook files modified

github-actions bot commented Mar 25, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: Install hook files modified

github-actions bot commented Mar 25, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: Install hook files modified

github-actions bot commented Mar 25, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: Install hook files modified

github-actions bot commented Mar 25, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: Install hook files modified

github-actions bot commented Mar 25, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: Install hook files modified

Uh oh!

Labels

5 participants

alt-glitch commented Feb 8, 2026 •

edited

Loading

sylvesterroos commented Mar 20, 2026 •

edited

Loading

lattwood commented Mar 23, 2026 •

edited

Loading