feat(nix): add home-manager module for per-user hermes-agent service

[yzx9]

What does this PR do?

Adds homeManagerModules.default exposing programs.hermes-agent with the same declarative config, MCP servers, documents, and settings as the NixOS module, but adapted for home-manager's user-scoped architecture.

Related Issue

Fixes #9056

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• systemd.user.services / launchd.agents instead of system-level services
• State dir defaults to ~/.local/share/hermes (XDG convention)
• home.activation for setup, no user/group creation needed

secret management:

sops-nix compatibility: sops-nix decrypts secrets during home.activation, which completes before any services start. No explicit service dependency is needed — ExecStartPre (Linux) and the launchd wrapper (Darwin) find the decrypted files already in place.

agenix compatibility: environmentFiles are appended to .env via ExecStartPre (runs after agenix decrypts secrets), not in the activation script. The service unit adds After/Wants on agenix.service when environmentFiles is non-empty.

A potential issue is that the secret may have been appended multiple times to the .env file. This could be resolved after #10139 is merged.

How to Test

1. Add the flake input (point at the feature branch for testing):
   inputs.hermes-agent.url = "github:yzx9/hermes-agent/feat/home-manager";
2. Import the module in your home-manager config:

   imports = [ hermes-agent.homeManagerModules.default ];
   programs.hermes-agent = {
     enable = true;                                                                                                                 
     settings.model = "anthropic/claude-sonnet-4";                                                                                  
     environmentFiles = [ config.sops.secrets.hermes-env.path ]; # optional                                                         
   };

3. Build and switch:

   # as nixos module
   sudo nixos-rebuild switch --flake .#your-profile
   # standalone
   home-manager switch --flake .#your-profile

4. Verify directory structure and config were generated:

   ls ~/.local/share/hermes/.hermes/config.yaml
   ls ~/.local/share/hermes/.hermes/.managed

5. Verify the service is running:

   # Linux
   systemctl --user status hermes-agent
   # macOS
   launchctl list | grep hermes
   

6. Verify secrets were injected (if using environmentFiles):

   cat ~/.local/share/hermes/.hermes/.env

7. Verify the gateway is healthy, say hello in the configured message platform

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: NixOS with latest nixpkgs-unstable and latest home-manager

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

• This skill is broadly useful to most users (if bundled) — see Contributing Guide
• SKILL.md follows the standard format (frontmatter, trigger conditions, steps, pitfalls)
• No external dependencies that aren't already available (prefer stdlib, curl, existing Hermes tools)
• I've tested the skill end-to-end: hermes --toolsets skills -q "Use the X skill to do Y"

Screenshots / Logs

[DavSanchez]

Not sure if it solves this problem, but Home Manager has options for setting up the colima runtime which might be leveraged for container mode.

[yzx9]

I notices that services.podman might also work. I can proceed with it if this PR can be merged

[sunny-g]

@yzx9 can you rebase with the changes made in #12208 🙏

[yzx9]

@sunny-g done

[sunny-g]

@yzx9 any chance you can rebase with the latest version v2026.4.23 (0.11.0)? :) :)

[yzx9]

@sunny-g sure

[sunny-g]

@yzx9 are you running hermes on a mac? I'm getting errors Executing pythonImportsCheckPhase (#16080) that was allegedly fixed in #15953.

[yzx9]

@sunny-g Hi, I’m not using it on Darwin at the moment, but I’m planning to give it a try next week. I regularly rebase to the latest release tag, though since the project is moving quickly, the releases may not always be up to date. I’ll rebase to the main branch as well. In the meantime, I’d suggest copying the first commit into your config, which enables you to integrate Home Manager with the latest Hermes agent. You can refer to yzx9/nix-config as an example.

[sunny-g]

@yzx9 way ahead of you and appreciate it :), think im just blocked by the python/av installation issues

[yzx9]

FYI, I’ve also run into the FFmpeg signing issue on aarch64-darwin with the latest nixpkgs-unstable. It might be related to NixOS/nixpkgs#513225.
I had to roll back to a previous commit since this affects many packages.
For this flake using uv2nix, switching to the prebuilt PyPI wheel might be a possible workaround

[teknium1]

Thanks for carrying the Home Manager implementation; current main still lacks this module, so the feature request in #9056 remains valid.

Problems

• nix/homeManagerModules.nix:516-524 appends every secret file to persistent .env on every service start. That duplicates entries and copies secret-manager output into Hermes state.
• nix/homeManagerModules.nix:536 and :617 export deprecated MESSAGING_CWD. Gateway startup calls warn_deprecated_cwd_env_vars() at gateway/run.py:1702-1703; hermes_cli/config.py:5402-5439 requires terminal.cwd instead.
• website/docs/getting-started/nix-setup.md:296 overstates parity: the Home Manager module lacks NixOS options declared at nix/nixosModules.nix:481, :502, and :527.
• The added checks cover managed-message text only; they do not evaluate homeManagerModules.default.

Suggested changes

• Use a non-duplicating secret-file design, migrate the working directory to settings.terminal.cwd, correct or complete the option-parity claim, and add Home Manager module evaluation coverage.

Automated hermes-sweeper review.

[teknium1]

This runs on every service start, so each restart appends the same secret file again to persistent .env. Please use a non-duplicating secret-file mechanism that also avoids copying secret-manager output into Hermes state.

[teknium1]

MESSAGING_CWD is deprecated: current gateway startup warns on it and requires terminal.cwd in config instead (gateway/run.py:1702-1703, hermes_cli/config.py:5402-5439). Configure the module's generated settings.terminal.cwd rather than exporting this environment variable.

[teknium1]

This parity claim is inaccurate: the Home Manager module does not define NixOS options extraPlugins, extraPythonPackages, or extraDependencyGroups (nix/nixosModules.nix:481, :502, :527). Please either implement them or document the supported subset.

[alt-glitch]

This was generated by AI during triage.

Related: #84178 implements the same Home Manager capability via a shared NixOS/Home Manager module refactor. These are competing approaches; maintainer review should choose the preferred design.

[yzx9]

closed as #84178 got merged