Skip to content

The agent that grows with you

docs(nix): extraDependencyGroups adds to the package's shipped groups

Teknium44b57c8af16f
diff --git a/nix/moduleCommon.nix b/nix/moduleCommon.nix
index 3d566552637..c0ec824be81 100644
--- a/nix/moduleCommon.nix
+++ b/nix/moduleCommon.nix
@@ -473,11 +473,16 @@ let
the sealed Python venv. These are resolved by uv alongside core
dependencies — no PYTHONPATH patching or collision risk.
+ They add to the groups `package` already ships (the default
+ package ships "messaging", "voice", "exa", ...); they never
+ replace them. For a smaller venv pick a smaller `package`
+ (`minimal`, `messaging`) or override its defaultDependencyGroups.
+
Use this for optional extras already declared in hermes-agent's
- pyproject.toml (e.g. "exa", "voice").
+ pyproject.toml (e.g. "google-meet").
Use extraPythonPackages for external packages not in pyproject.toml.
'';
- example = [ "voice" ];
+ example = [ "google-meet" ];
};
# ── Service behaviour ──────────────────────────────────────────────
diff --git a/website/docs/getting-started/nix-setup.md b/website/docs/getting-started/nix-setup.md
index d378b55f79c..a87b913776e 100644
--- a/website/docs/getting-started/nix-setup.md
+++ b/website/docs/getting-started/nix-setup.md
@@ -368,7 +368,7 @@ Quick reference for the most common things Nix users want to customize:
| Add project context to the workspace | `documents."AGENTS.md"` | `./documents/AGENTS.md` |
| Run the backend for the desktop app or the dashboard | `backend.mode` | `"serve"` or `"dashboard"` |
| Add MCP tool servers | `mcpServers.<name>` | See [MCP Servers](#mcp-servers) |
-| Enable Discord/Telegram/Slack | `extraDependencyGroups` | `[ "messaging" ]` |
+| Add an optional extra the package does not ship | `extraDependencyGroups` | `[ "google-meet" ]` |
| Mount host directories into container | `container.extraVolumes` | `[ "/data:/data:rw" ]` |
| Pass GPU access to container | `container.extraOptions` | `[ "--gpus" "all" ]` |
| Use Podman instead of Docker | `container.backend` | `"podman"` |
@@ -819,13 +819,15 @@ The package's `site-packages` is added to PYTHONPATH in the hermes wrapper. `imp
### Optional Dependency Groups (`extraDependencyGroups`)
-For optional extras declared in hermes-agent's `pyproject.toml`, use `extraDependencyGroups` to include them in the sealed venv at build time. This is required for any extra not in the default `[all]` set — on Nix, runtime installation into the read-only store is not possible.
+For optional extras declared in hermes-agent's `pyproject.toml`, use `extraDependencyGroups` to include them in the sealed venv at build time. This is required for any extra the selected package does not already ship — on Nix, runtime installation into the read-only store is not possible.
```nix
-# Enable Discord, Telegram, Slack
-services.hermes-agent.extraDependencyGroups = [ "messaging" ];
+# Add Google Meet support on top of what the package ships
+services.hermes-agent.extraDependencyGroups = [ "google-meet" ];
```
+`extraDependencyGroups` and `extraPythonPackages` **add to** the groups the selected package ships; they never replace them. The `default` package already ships `messaging`, `voice`, `exa` and the other groups in the table below, so naming one of those changes nothing. The same holds for `pkgs.hermes-agent.override { extraDependencyGroups = [ ... ]; }`. For a smaller build, start from a smaller package: `package = inputs.hermes-agent.packages.${system}.minimal;` (or `#messaging`), or `.override { defaultDependencyGroups = [ ]; }` to drop the shipped groups and list only the ones you want.
+
These groups join the core dependency resolution at build time. Conflicting
requirements can still fail that resolution. The table lists common groups;
`pyproject.toml` is authoritative for the complete list and platform markers.
@@ -884,7 +886,9 @@ External flakes can override the package directly:
nixpkgs.overlays = [ hermes-agent.overlays.default ];
# Then:
# pkgs.hermes-agent.override { extraPythonPackages = [...]; }
- # pkgs.hermes-agent.override { extraDependencyGroups = [ "voice" ]; }
+ # pkgs.hermes-agent.override { extraDependencyGroups = [ "google-meet" ]; }
+ # Both add to the groups the default package ships. To drop those:
+ # pkgs.hermes-agent.override { defaultDependencyGroups = [ ]; }
};
}
```
@@ -1030,7 +1034,7 @@ nix build .#checks.x86_64-linux.config-roundtrip # merge script preserves use
| `extraPackages` | `listOf package` | `[]` | Extra packages available to the agent. Added to the hermes user's per-user profile so terminal commands, skills, and cron jobs all see them |
| `extraPlugins` | `listOf package` | `[]` | Directory plugin packages to symlink into `$HERMES_HOME/plugins/`. Each must contain `plugin.yaml` |
| `extraPythonPackages` | `listOf package` | `[]` | Python packages added to PYTHONPATH for entry-point plugin discovery. Use the selected package’s `python.pkgs` |
-| `extraDependencyGroups` | `listOf str` | `[]` | pyproject.toml optional extras to include in the sealed venv (e.g. `["voice"]`). Resolved by uv — no collisions |
+| `extraDependencyGroups` | `listOf str` | `[]` | pyproject.toml optional extras added to the groups `package` already ships (e.g. `["google-meet"]`). Resolved by uv — no collisions |
| `restart` | `str` | `"always"` | The systemd `Restart=` policy. macOS does not use it. |
| `restartSec` | `int` | `5` | The systemd `RestartSec=` value. macOS does not use it. |
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/nix-setup.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/nix-setup.md
index 7eacda8fd41..50748968e64 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/nix-setup.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/nix-setup.md
@@ -658,16 +658,16 @@ services.hermes-agent.extraPythonPackages = [
### 可选依赖组(`extraDependencyGroups`)
-对于已在 hermes-agent 的 `pyproject.toml` 中声明的可选 extras(例如 `honcho` 等记忆提供商),使用 `extraDependencyGroups` 在构建时将其包含到封闭的 venv 中:
+对于已在 hermes-agent 的 `pyproject.toml` 中声明、但所选包尚未附带的可选 extras,使用 `extraDependencyGroups` 在构建时将其包含到封闭的 venv 中:
```nix
-services.hermes-agent = {
- extraDependencyGroups = [ "honcho" ];
- settings.memory.provider = "honcho";
-};
+# 在包已附带的组之上添加 Google Meet 支持
+services.hermes-agent.extraDependencyGroups = [ "google-meet" ];
```
-这由 uv 与核心依赖在单次解析中完成——不需要 PYTHONPATH 补丁,没有冲突风险。可用的组与 `pyproject.toml` 中 `[project.optional-dependencies]` 的键对应(例如 `"honcho"`、`"voice"`、`"matrix"`、`"mistral"`、`"bedrock"`)。
+这由 uv 与核心依赖在单次解析中完成——不需要 PYTHONPATH 补丁,没有冲突风险。可用的组与 `pyproject.toml` 中 `[project.optional-dependencies]` 的键对应(例如 `"google-meet"`、`"voice"`、`"matrix"`、`"mistral"`、`"bedrock"`)。
+
+`extraDependencyGroups` 和 `extraPythonPackages` 是在所选包已附带的组之上**追加**,从不替换它们。`default` 包已附带 `messaging`、`voice`、`exa` 等组,因此再写这些组不会有任何变化;`pkgs.hermes-agent.override { extraDependencyGroups = [ ... ]; }` 同理。如需更小的构建,请从更小的包开始:`package = inputs.hermes-agent.packages.${system}.minimal;`(或 `#messaging`),或使用 `.override { defaultDependencyGroups = [ ]; }` 去掉附带的组,只列出你需要的组。
**何时使用哪个:**
@@ -701,7 +701,9 @@ services.hermes-agent = {
nixpkgs.overlays = [ hermes-agent.overlays.default ];
# 然后:
# pkgs.hermes-agent.override { extraPythonPackages = [...]; }
- # pkgs.hermes-agent.override { extraDependencyGroups = [ "honcho" ]; }
+ # pkgs.hermes-agent.override { extraDependencyGroups = [ "google-meet" ]; }
+ # 两者都是在 default 包附带的组之上追加。要去掉附带的组:
+ # pkgs.hermes-agent.override { defaultDependencyGroups = [ ]; }
};
}
```
@@ -844,7 +846,7 @@ nix build .#checks.x86_64-linux.config-roundtrip # 合并脚本保留用户
| `extraPackages` | `listOf package` | `[]` | Agent 可用的额外包。添加到 hermes 用户的每用户 profile,终端命令、skills 和 cron 任务均可见 |
| `extraPlugins` | `listOf package` | `[]` | 以符号链接方式安装到 `$HERMES_HOME/plugins/` 的目录插件包。每个包必须包含 `plugin.yaml` |
| `extraPythonPackages` | `listOf package` | `[]` | 添加到 PYTHONPATH 用于入口点插件发现的 Python 包。使用所选包的 `python.pkgs` 构建 |
-| `extraDependencyGroups` | `listOf str` | `[]` | 包含到封闭 venv 中的 pyproject.toml 可选 extras(例如 `["honcho"]`)。由 uv 解析——无冲突 |
+| `extraDependencyGroups` | `listOf str` | `[]` | 在 `package` 已附带的组之上追加的 pyproject.toml 可选 extras(例如 `["google-meet"]`)。由 uv 解析——无冲突 |
| `restart` | `str` | `"always"` | systemd `Restart=` 策略 |
| `restartSec` | `int` | `5` | systemd `RestartSec=` 值 |