hyperhive — per-agent options

hyperhive.allowedRecipients

Names this agent is allowed to send to via mcp__hyperhive__send. Empty list (the default) means unrestricted — the agent can message any peer, the operator, or the manager. Non-empty list constrains the surface: only the listed names + the manager (always allowed) get through; anything else returns an error string to claude without touching the broker. The operator (operator) needs to be in the list if the agent should be able to surface output on the dashboard.

Useful for sandboxing untrusted sub-agents — set [ "manager" ] to scope them to manager-only chatter. The manager itself is always exempt; this option only affects sub-agent send.

Type: list of string

Default:

[ ]

Example:

[
  "alice"
  "manager"
]

Declared by:

hyperhive.autoCompact

Enable proactive watermark-based compaction. When true (the default) the harness automatically runs a notes-checkpoint turn followed by /compact once the context window crosses 75% of the model’s limit, keeping later turns from hitting the hard overflow path. Set to false to disable proactive compaction entirely (HIVE_COMPACT_WATERMARK_TOKENS=0); the reactive path (compact-on-overflow when the session is already past the limit) still applies.

Disable for agents that run large-context models (sonnet/opus) where the heuristic fires too early and discards useful history before the session is actually close to the limit.

Type: boolean

Default:

true

Declared by:

hyperhive.availableModels

Models offered in the per-agent web UI’s model quick-picker. Rendered into the HIVE_AVAILABLE_MODELS environment variable (comma-separated) which the harness surfaces to the agent UI, so the picker lists exactly these models instead of a hardcoded set.

Configure hive-wide by setting a shared default (e.g. in your agent-base.nix) or per-agent to narrow the menu — for example a haiku-only agent can hide opus and sonnet. The current model is still set by hyperhive.model and remains switchable at runtime via the UI; this option only controls which choices the picker presents.

Values are the short model names that claude --model accepts: "haiku", "sonnet", "opus" (or any future identifier).

Type: list of string

Default:

[
  "haiku"
  "sonnet"
  "opus"
]

Example:

[
  "sonnet"
  "opus"
]

Declared by:

hyperhive.cargo.shortMessages

Auto-inject --message-format short on cargo compile subcommands (build, check, clippy, test, run, doc, bench, install, rustc, fix) when claude (or anything else) invokes cargo inside this container. Saves tokens + context — the verbose default output floods the response window with per-crate progress lines that carry no signal beyond the warning/error summary.

Implementation: contributes a cargo shell function to /etc/hyperhive/bash-env.sh (see hyperhive._bashEnvFragments). Loaded via BASH_ENV for non-interactive shells (bash -c — what the claude Bash tool runs) and sourced from programs.bash.interactiveShellInit for interactive shells. The function:

Set to false for agents that need full cargo output (e.g. tooling that parses --message-format json programmatically and doesn’t pass the flag explicitly).

Type: boolean

Default:

true

Example:

false

Declared by:

hyperhive.claudeMarketplaces

Claude Code plugin marketplaces to add at harness boot. Each entry is passed to claude plugin marketplace add <source> (owner/repo, full git URL, or local path). Idempotent — re-adding an existing marketplace is treated as success. Required before hyperhive.claudePlugins entries that reference a marketplace (e.g. foo@claude-plugins-official). Rendered to /etc/hyperhive/claude-marketplaces.json.

Defaults to Anthropic’s official marketplace; agents get it out of the box without any per-agent.nix wiring.

Type: list of string

Default:

[
  "anthropics/claude-plugins-official"
]

Example:

[
  "anthropics/claude-plugins-official"
  "anthropics/claude-plugins-community"
]

Declared by:

hyperhive.claudePlugins

Claude Code plugins to install at harness boot. Each entry is passed verbatim to claude plugin install <spec> once per container start, before the turn loop opens. claude plugin install is expected to be idempotent, so reinstalling on every boot is cheap. Failures log a warning but do not abort boot — a missing plugin is preferable to a non-serving agent. Rendered to /etc/hyperhive/claude-plugins.json; the harness reads it via plugins::install_configured.

Type: list of string

Default:

[ ]

Example:

[
  "formatter@my-marketplace"
  "thinking-tools@anthropics"
]

Declared by:

hyperhive.claudePluginsAutoUpdate

When true, the harness runs claude plugin marketplace update before installing plugins at boot, pulling the latest index from all configured marketplaces. Disabled by default — most agents want pinned plugin versions and the network round-trip adds to boot time. Enable for agents that should always install the latest available version of their plugins.

Type: boolean

Default:

false

Declared by:

Extra navigation links surfaced on the hive-c0re dashboard card for this agent. Declare any additional web UI pages the agent exposes — stats pages, custom UIs, etc. hive-c0re reads the JSON file this option produces at each container-view snapshot and attaches the links to the agent card without any code changes.

Type: list of (submodule)

Default:

[ ]

Example:

[
  { label = "Stats"; icon = "📊"; url = "http://localhost:9001/stats"; }
]

Declared by:

hyperhive.dashboardLinks.*.icon

Optional icon emoji or short glyph.

Type: string

Default:

""

Declared by:

hyperhive.dashboardLinks.*.label

Display label for the link.

Type: string

Declared by:

hyperhive.dashboardLinks.*.url

Full URL (may include a different port, e.g. http://localhost:9001/stats)\.

Type: string

Declared by:

hyperhive.extraMcpServers

Extra MCP servers claude sees alongside the hyperhive tool surface. Keys are the server names (claude addresses tools as mcp__<key>__<tool>). Rendered to /etc/hyperhive/extra-mcp.json at activation time; the harness reads that file at boot and merges it into --mcp-config + --allowedTools. Take effect on the agent’s next harness restart (no operator approval needed beyond whatever brought the new agent.nix into deployed/*).

Type: attribute set of (submodule)

Default:

{ }

Example:

{
  matrix = {
    command = "/run/current-system/sw/bin/mcp-matrix";
    args = [ "--config" "/state/matrix.toml" ];
    env.MATRIX_HOMESERVER = "https://matrix.example.org";
    allowedTools = [ "send_message" "join_room" ];
  };
}

Declared by:

hyperhive.extraMcpServers.<name>.allowedTools

Tool names this MCP server is auto-approved to call via --allowedTools. Single entry "*" (the default) means “every tool from this server” — convenient but trusting. Tighten to a specific list when you only want a subset. Names are bare (e.g. send_message); the harness prepends mcp__<server-key>__ at build time.

Type: list of string

Default:

[
  "*"
]

Example:

[
  "send_message"
  "join_room"
]

Declared by:

hyperhive.extraMcpServers.<name>.args

Args passed to the MCP server binary.

Type: list of string

Default:

[ ]

Declared by:

hyperhive.extraMcpServers.<name>.command

Absolute path to the MCP server binary. Use ${pkgs.foo}/bin/foo or /run/current-system/sw/bin/foo.

Type: string

Declared by:

hyperhive.extraMcpServers.<name>.env

Environment variables for the MCP server child process.

Type: attribute set of string

Default:

{ }

Declared by:

hyperhive.forge.keepSubscriptions

When true (the default), the forge notification poller will NOT auto-unsubscribe from repo watches after delivering a “subscribed”-reason notification. Sub-agents keep their broad subscriptions so they stay informed about repos they contribute to. Set to false for agents (e.g. the manager) that use reason-based filtering and do not need firehose-level repo visibility — they will auto-unsubscribe after receiving a watched-repo notification.

Type: boolean

Default:

true

Declared by:

hyperhive.forge.skipNotifyReasons

Forgejo notification reason values to suppress in the forge notification poller. Notifications with these reasons are marked read and silently dropped; all others — including notifications with a null or unrecognised reason — are delivered.

Drop-list is safer than an allow-list: directed signals (review_requested, assigned, mention) are never silently missed even if Forgejo returns an unexpected reason string.

Empty list (the default) delivers all notifications. Set to [ "subscribed" "participating" ] for agents like the manager that want only direct mentions and reviews, not the full repo firehose. Rendered to the HIVE_FORGE_NOTIFY_SKIP_REASONS environment variable consumed by the harness poller at runtime.

Type: list of string

Default:

[ ]

Example:

[
  "subscribed"
  "participating"
]

Declared by:

hyperhive.forge.url

Base URL of the hyperhive-managed Forgejo. Used at container boot by a oneshot systemd unit that calls tea login add --url <this> --token "$(cat $HYPERHIVE_STATE_DIR/forge-token)" (= /agents/<name>/state/forge-token) so the agent’s claude can shell out to tea without an extra auth dance. No-op when the forge-token file is missing (i.e. hive-forge isn’t running on the host).

Type: string

Default:

"http://localhost:3000"

Example:

"http://forge.internal:3000"

Declared by:

hyperhive.frontend.dist

The shipped frontend dist (built by nix/frontend.nix). Output layout: dashboard/ (used by hive-c0re on the host) and agent/ (used here, layered with extraFiles below at activation time). Override to ship a fully custom per-agent SPA; the JSON contract (/api/state, /events/stream, the action endpoints) is the source of truth for any replacement.

Type: package

Default:

pkgs.hyperhive-frontend

Declared by:

hyperhive.frontend.extraFiles

Per-agent additions layered on top of the default frontend dist. Each entry copies its source into the served static tree under target. Useful for shipping a self-contained agent-specific surface alongside the standard agent UI (e.g. the bitburner agent’s game page at /bitburner/).

The default agent UI remains served at /; entries here only add new routes and never replace the default. Overwrite semantics are hard-fail: if target collides with an existing file or directory in the default dist (or with a prior entry’s target), the mergedDist build aborts with refusing to overwrite existing path '<target>' in the default dist. To override a default file, fork the dist via hyperhive.frontend.dist instead — extraFiles is for pure additions.

target must be a relative path inside the static dir. An assertion rejects leading / and .. segments at config eval time (string-concat-into-paths safety, even though agent.nix goes through operator review before deploy).

Type: attribute set of (submodule)

Default:

{ }

Example:

{
  bitburner = {
    source = ./bitburner-dist;
    # served at GET /bitburner/...
  };
}

Declared by:

hyperhive.frontend.extraFiles.<name>.source

Source file or directory to layer over the default agent dist. A path (relative to agent.nix or absolute) — nix copies its contents into the merged static tree.

Type: absolute path

Declared by:

hyperhive.frontend.extraFiles.<name>.target

Destination path within the merged static tree, used as both the served URL prefix (/<target>/...) and the on-disk layout in the merged derivation. Defaults to the attribute name. Use forward slashes for nested layouts (e.g. "games/bitburner").

Constrained shape: must start with an alphanumeric or _, and only contain alphanumerics, _, ., /, -. .. segments are separately rejected at config eval time.

Type: string matching the pattern ^[A-Za-z0-9_][A-Za-z0-9_./-]*$

Default: the attribute name

Declared by:

hyperhive.frontend.mergedDist

Computed: the merged static tree consumed by the harness via HIVE_STATIC_DIR. Composed at evaluation time by copying hyperhive.frontend.dist’s agent/ subdir as the base, then layering each extraFiles entry on top. Read-only — do not set directly.

Type: package (read only)

Declared by:

hyperhive.gui.enable

Run Weston with the VNC backend as a systemd service, for in-browser GUI access via the harness /screen/ws WebSocket relay. Renders in software (pixman) — no GPU, DRM, or VT access, so no extra container capabilities are needed.

The VNC port is a deterministic FNV-1a hash of the agent name mapped into [15900, 16799], written to /etc/hyperhive/gui.json at service start so the harness can relay connections without a separate config flag. The unit is Type = "simple" so a misconfigured weston degrades to a restart loop instead of blocking nixos-container update.

Type: boolean

Default:

false

Declared by:

hyperhive.icon

Path to an SVG file used as this agent’s icon — shown on the dashboard and the per-agent web UI (header + favicon). Commit the SVG into the agent’s config repo next to agent.nix and reference it as a relative path (./icon.svg).

When null (the default) the agent falls back to the shared hyperhive logo. The harness serves the icon (configured or default) at GET /icon on the per-agent web port.

Type: null or absolute path

Default:

null

Example:

./icon.svg

Declared by:

hyperhive.matrix.enable

Enable per-agent matrix integration via hive-matrix-mcp. When true (the default), the harness:

Set to false for agents that should NOT have matrix tools at all (e.g. agents on a host without hyperhive.matrix.enable on the meta side). When token file is absent the daemon and MCP both no-op cleanly anyway, so false is rarely necessary.

Type: boolean

Default:

true

Declared by:

hyperhive.matrix.url

Matrix homeserver URL the agent’s hive-matrix-daemon connects to. Default points at the in-host tuwunel (shared netns). Override per-agent when an agent should talk to an external homeserver instead (e.g. a federation-only setup or a remote hive’s tuwunel reached via a vpn).

Type: string

Default:

"http://localhost:8008"

Example:

"https://matrix.darkest.space"

Declared by:

hyperhive.model

Claude model for this agent. Sets the HIVE_DEFAULT_MODEL environment variable; the harness applies it at boot and it takes priority over any persisted runtime override. The operator can still switch the model at runtime via the per-agent web UI — that choice is tracked in the state dir for the current session but is reset by any rebuild that changes this option.

Valid values are the short model names that claude --model accepts: "haiku", "sonnet", "opus" (or any future identifier). Context window sizes are looked up at runtime from the HIVE_CONTEXT_WINDOW_TOKENS_<KEY_UPPER> env vars injected by the meta flake; override sizes via services.hyperhive.c0re.contextWindowTokens on the host.

Type: string

Default:

"haiku"

Example:

"sonnet"

Declared by:

hyperhive.user.name

Unix user the harness service runs as inside the container. The meta-flake overrides this to the agent’s own name so the user inside the container matches the agent label (HIVE_LABEL). Stand-alone evaluation defaults to "agent" so module evaluation without the meta-flake wrapper still builds.

Constraints match useradd’s NAME_REGEX: lowercase / _ start, total length ≤ 31, no special characters. UID is auto-assigned by NixOS; no uid = override surface (intentional — pinning across rebuilds isn’t a concern when the home and state dirs stay bind-mounted from the host).

Type: string matching the pattern ^[a-z_][a-z0-9_-]{0,30}$

Default:

"agent"

Example:

"iris"

Declared by:

hyperhive.user.passwordlessSudo

Grant agent passwordless sudo (NOPASSWD: ALL). True by default so claude’s Bash tool keeps working for tools that expect root inside the container (systemctl, package managers in dev shells, etc.) — the same surface the previous root-user shape had, just elevated explicitly instead of implicitly.

Flip to false for agents that should be strictly unprivileged. Anything claude shells out to that needs root will then fail loudly with the standard sudo error rather than silently succeeding — easier to spot the leak.

Type: boolean

Default:

true

Example:

false

Declared by:

hyperhive.web.useUnixSocket

Deprecated. Unix socket mode is now always enabled for all agents. Setting this option to true has no effect and the option will be removed in a future version. Safe to drop from agent configs.

Type: boolean

Default:

false

Example:

true

Declared by: