feat(nix): declarative plugin installation for NixOS module by alt-glitch · Pull Request #15953 · NousResearch/hermes-agent

alt-glitch · 2026-04-26T08:19:27Z

Summary

Enable NixOS users to declaratively install hermes plugins — both directory-based and pip-packaged — without manual PYTHONPATH hacks or imperative installs.

Closes #14453

What changed

Package refactor (Nix hygiene):

Extract the inline stdenv.mkDerivation from packages.nix into a standalone nix/hermes-agent.nix — now callPackage-able and overridable via .override{}
Add nix/overlays.nix exposing pkgs.hermes-agent for external flakes
Parameterize dependency-groups in python.nix (default ["all"], preserves current behavior)

Plugin support (new feature):

New extraPythonPackages parameter on the package derivation — when non-empty, makeWrapper appends plugin site-packages to PYTHONPATH via --suffix
Build-time collision check using PEP 503 canonical name normalization — fails the build if a plugin package shadows a core hermes dependency
New NixOS module option extraPlugins (directory plugins) — symlinks packages into HERMES_HOME/plugins/ at activation time with nix-managed- prefix, validates plugin.yaml presence, asserts unique names at eval time
New NixOS module option extraPythonPackages (entry-point plugins) — overrides the hermes package with PYTHONPATH injection, works in both native systemd and container modes

Documentation:

New "Plugins" section in nix-setup.md with examples for both plugin types, overlay usage, and collision checking
NixOS row in plugin discovery table in plugins.md
"Distribute for NixOS" section in build-a-hermes-plugin.md

Usage

services.hermes-agent = {
  enable = true;

  # Directory plugin (source tree with plugin.yaml)
  extraPlugins = [
    (pkgs.fetchFromGitHub {
      owner = "stephenschoettler";
      repo = "hermes-lcm";
      rev = "v0.7.0";
      hash = "sha256-...";
    })
  ];

  # Entry-point plugin (pip package with hermes_agent.plugins entry point)
  extraPythonPackages = [
    (pkgs.python312Packages.buildPythonPackage {
      pname = "rtk-hermes";
      version = "1.0.0";
      src = pkgs.fetchFromGitHub { owner = "ogallotti"; repo = "rtk-hermes"; rev = "v1.0.0"; hash = "sha256-..."; };
      format = "pyproject";
      build-system = [ pkgs.python312Packages.setuptools ];
    })
  ];

  # Enable plugins in config
  settings.plugins.enabled = [ "hermes-lcm" "rtk-rewrite" ];
};

External flakes:

overlays = [ inputs.hermes-agent.overlays.default ];
# Then: pkgs.hermes-agent.override { extraPythonPackages = [...]; }

How it works

Directory plugins: Activation script symlinks each extraPlugins entry into $HERMES_HOME/plugins/nix-managed-<name>. Hermes discovers them via its normal directory scan. Stale symlinks are cleaned up on every activation.
Entry-point plugins: The package derivation is rebuilt with extraPythonPackages baked into the wrapper's PYTHONPATH. importlib.metadata.entry_points() discovers the plugins at session start. No extra volume mounts needed in container mode — /nix/store is already mounted at the same path.
Collision check: A Python script in the install phase scans plugin .dist-info/METADATA against the core venv using PEP 503 canonical names. Collisions fail the build.
GC safety: Plugin store paths appear as literal strings in the wrapper script. Nix's reference scanner detects them — they're protected from garbage collection as long as the hermes-agent derivation is alive.

Verified

nix build passes (hermes v0.11.0, all three binaries present)
nix build .#checks.x86_64-linux.extra-python-packages passes (pyfiglet injected, PYTHONPATH verified)
Collision check correctly blocks pydantic (core dep) with clear error
End-to-end test: built hermes with a custom test plugin, importlib.metadata discovered the entry point, register(ctx) called, tool registered (32 tools, up from 31), LLM called the plugin tool successfully
Overlay evaluates ("lambda")
Duplicate plugin name assertion fires at eval time

Prior art

Follows established nixpkgs patterns:

extraPlugins → Nextcloud/Grafana (symlink into discovery directory)
extraPythonPackages → Home Assistant/Maubot (package override with PYTHONPATH)

Makes the package overridable via .override{} and adds extraPythonPackages parameter for PYTHONPATH injection. Includes build-time collision check using PEP 503 name canonicalization.

External flakes can now add overlays = [ inputs.hermes-agent.overlays.default ] to get pkgs.hermes-agent with full .override support.

Verifies wrapper has PYTHONPATH when extras provided, and base package has no PYTHONPATH without extras.

Symlinks plugin packages into HERMES_HOME/plugins/ at activation time. Validates plugin.yaml presence. Asserts unique plugin names at eval time. Hermes discovers them automatically via its directory scan.

Overrides the hermes package with PYTHONPATH injection when extraPythonPackages is non-empty. Plugin .dist-info directories become visible to importlib.metadata for entry-point discovery. Works in both native systemd and container modes.

…, and build-a-plugin guides - nix-setup.md: new Plugins section with extraPlugins/extraPythonPackages examples, overlay usage, collision checking note, options reference rows - plugins.md: Nix row in discovery table, NixOS declarative plugins section - build-a-hermes-plugin.md: Distribute for NixOS section after pip section

alt-glitch · 2026-04-26T08:20:26Z

@BugBot review

…itHub naming, simplify checks - Remove accidentally introduced umask/migration changes (unrelated to plugins) - Add pluginName helper, fix fetchFromGitHub producing name='source' - Show name= in extraPlugins example docs - Simplify checks.nix: use hermes-agent.override instead of re-callPackage - Fix fragile grep shell logic in checks

…', Python list for extras - Use lib.getName instead of custom pluginName helper - Drop unused inputs' from checks.nix perSystem args - Pass extraPythonPackages as Python list literal instead of colon-split string

…heck Uses python312.pkgs.requiredPythonModules to resolve the full transitive closure of extraPythonPackages. Without this, a plugin with third-party deps (e.g. requests) would fail at runtime if those deps weren't already in the sealed uv2nix venv. The collision check now also scans the full closure, catching transitive conflicts.

alt-glitch · 2026-04-26T08:52:44Z

@BugBot review

… inline lib.getName - Add 'plugins' to the existing cron/sessions/logs/memories subdir loop instead of a separate mkdir/chown/chmod block - Replace fragile for-glob with find -delete for stale symlink cleanup - Inline lib.getName at both call sites, remove pluginName wrapper

cursor

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit bd0a6e6. Configure here.}

…arch#15953) * feat(nix): parameterize dependency-groups in python.nix * refactor(nix): extract package to callPackage-able hermes-agent.nix Makes the package overridable via .override{} and adds extraPythonPackages parameter for PYTHONPATH injection. Includes build-time collision check using PEP 503 name canonicalization. * feat(nix): add overlay for external NixOS consumption External flakes can now add overlays = [ inputs.hermes-agent.overlays.default ] to get pkgs.hermes-agent with full .override support. * test(nix): add check for extraPythonPackages PYTHONPATH injection Verifies wrapper has PYTHONPATH when extras provided, and base package has no PYTHONPATH without extras. * feat(nix): add extraPlugins option for directory-based plugins Symlinks plugin packages into HERMES_HOME/plugins/ at activation time. Validates plugin.yaml presence. Asserts unique plugin names at eval time. Hermes discovers them automatically via its directory scan. * feat(nix): add extraPythonPackages option for entry-point plugins Overrides the hermes package with PYTHONPATH injection when extraPythonPackages is non-empty. Plugin .dist-info directories become visible to importlib.metadata for entry-point discovery. Works in both native systemd and container modes. * docs: add NixOS declarative plugin installation to nix-setup, plugins, and build-a-plugin guides - nix-setup.md: new Plugins section with extraPlugins/extraPythonPackages examples, overlay usage, collision checking note, options reference rows - plugins.md: Nix row in discovery table, NixOS declarative plugins section - build-a-hermes-plugin.md: Distribute for NixOS section after pip section * fix: address review feedback — remove unrelated umask, fix fetchFromGitHub naming, simplify checks - Remove accidentally introduced umask/migration changes (unrelated to plugins) - Add pluginName helper, fix fetchFromGitHub producing name='source' - Show name= in extraPlugins example docs - Simplify checks.nix: use hermes-agent.override instead of re-callPackage - Fix fragile grep shell logic in checks * refactor: address simplify feedback — lib.getName, drop unused inputs', Python list for extras - Use lib.getName instead of custom pluginName helper - Drop unused inputs' from checks.nix perSystem args - Pass extraPythonPackages as Python list literal instead of colon-split string * fix: walk propagatedBuildInputs for plugin PYTHONPATH and collision check Uses python312.pkgs.requiredPythonModules to resolve the full transitive closure of extraPythonPackages. Without this, a plugin with third-party deps (e.g. requests) would fail at runtime if those deps weren't already in the sealed uv2nix venv. The collision check now also scans the full closure, catching transitive conflicts. * cleanup: fold plugins into subdir loop, use find for symlink cleanup, inline lib.getName - Add 'plugins' to the existing cron/sessions/logs/memories subdir loop instead of a separate mkdir/chown/chmod block - Replace fragile for-glob with find -delete for stale symlink cleanup - Inline lib.getName at both call sites, remove pluginName wrapper

alt-glitch added 7 commits April 26, 2026 12:55

feat(nix): parameterize dependency-groups in python.nix

44287fb

refactor(nix): extract package to callPackage-able hermes-agent.nix

6c223aa

Makes the package overridable via .override{} and adds extraPythonPackages parameter for PYTHONPATH injection. Includes build-time collision check using PEP 503 name canonicalization.

feat(nix): add overlay for external NixOS consumption

8efcea4

External flakes can now add overlays = [ inputs.hermes-agent.overlays.default ] to get pkgs.hermes-agent with full .override support.

test(nix): add check for extraPythonPackages PYTHONPATH injection

b2948ee

Verifies wrapper has PYTHONPATH when extras provided, and base package has no PYTHONPATH without extras.

feat(nix): add extraPlugins option for directory-based plugins

bcf136c

Symlinks plugin packages into HERMES_HOME/plugins/ at activation time. Validates plugin.yaml presence. Asserts unique plugin names at eval time. Hermes discovers them automatically via its directory scan.

alt-glitch added type/feature New feature or request comp/plugins Plugin system and bundled plugins area/nix Nix flake, NixOS module, container packaging labels Apr 26, 2026

alt-glitch mentioned this pull request Apr 26, 2026

feat(nix): declarative plugin installation for NixOS module #14453

Closed

5 tasks

alt-glitch marked this pull request as draft April 26, 2026 08:20

cursor Bot reviewed Apr 26, 2026

View reviewed changes

Comment thread nix/checks.nix Outdated

alt-glitch added the P3 Low — cosmetic, nice to have label Apr 26, 2026

alt-glitch added 3 commits April 26, 2026 14:07

cursor Bot reviewed Apr 26, 2026

View reviewed changes

alt-glitch marked this pull request as ready for review April 27, 2026 00:58

alt-glitch requested a review from ethernet8023 April 27, 2026 00:59

alt-glitch merged commit ef41d3b into main Apr 27, 2026
10 of 11 checks passed

alt-glitch deleted the sid/nix-overlay branch April 27, 2026 18:48

This was referenced Apr 27, 2026

fix(nix): skip av/faster-whisper build checks on aarch64-darwin #16080

Closed

[Feature]: nix package should support source patching #16537

Open

github-actions Bot mentioned this pull request May 1, 2026

chore: bump NousResearch/hermes-agent version from v2026.4.23 to v2026.4.30 Docker-Hub-sirmark/docker-hermes-agent#4

Merged

sunny-g mentioned this pull request May 1, 2026

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

Open

23 tasks

thattemperature mentioned this pull request May 30, 2026

feat(nix): change extraPythonPackages from listOf package to functionTo #35350

Open

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(nix): declarative plugin installation for NixOS module#15953

feat(nix): declarative plugin installation for NixOS module#15953
alt-glitch merged 11 commits into
mainfrom
sid/nix-overlay

alt-glitch commented Apr 26, 2026 •

edited

Loading

Uh oh!

alt-glitch commented Apr 26, 2026

Uh oh!

Uh oh!

alt-glitch commented Apr 26, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

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

Uh oh!

Summary

What changed

Usage

How it works

Verified

Prior art

Uh oh!

alt-glitch commented Apr 26, 2026

Uh oh!

Uh oh!

alt-glitch commented Apr 26, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

alt-glitch commented Apr 26, 2026 •

edited

Loading