a1243fe04a
The three moves above falsify prose in five files, and none of it is caught by a gate: clippy, cargo test and nix flake check read exactly zero markdown. Corrected where a doc stated a DEFAULT or enumerated the vhosts -- gateway (ACME requirements + the header table + the two Forgejo reachability lines), matrix (gatewayHost, firewall rationale, agent reachability), network (container table + the HTTP resolution bullet), turn-loop config, dashboard. Two mentions are deliberately left alone. `docs/tools/hivectl.md` says the URL is read from the daemon "instead of assuming forge.<domain>" -- that sentence is about not assuming a shape and stays true. And matrix.md's breaking-change note describes what `serverName` USED to default to; it is history, correctly labelled, and rewriting it would erase the record of an earlier migration. The ACME line gained a requirement rather than a rename: with the service names under the swarm domain, every one of those names has to resolve to this host, not just the hive's own.
228 lines
9.8 KiB
Markdown
228 lines
9.8 KiB
Markdown
# Agent config knobs
|
|
|
|
Optional per-agent knobs the meta flake wires into the container from
|
|
`services.hyperhive.agents.<name>`, read at boot or per turn by the harness.
|
|
Absent means the default. (The claude spawn + compaction themselves live in
|
|
[claude-invocation](claude-invocation.md).)
|
|
|
|
## Reference docs (`hyperhive.docs.enable`)
|
|
|
|
```nix
|
|
hyperhive.docs.enable = true; # default: false (true for the manager agent)
|
|
```
|
|
|
|
Makes the hyperhive `docs/` tree available inside the container at a nix
|
|
store path read from `$HIVE_DOCS_DIR`, and injects a single pointer
|
|
sentence into the agent's system prompt so it knows the docs exist and
|
|
where to find them. The tree is served by `claude --add-dir` so the full
|
|
markdown is readable during every turn.
|
|
|
|
Enabled by default only for the root/manager agent (`nix/templates/ruth.nix`). Any
|
|
agent can opt in by adding the line above to its `agent.nix`.
|
|
|
|
The `docs/` source is a narrow flake input (`hyperhive-docs`) tracked
|
|
separately from the main `hyperhive` flake so editing docs re-locks only
|
|
that input — not every agent's container gets rebuilt on a doc-only change.
|
|
|
|
## Agent icon
|
|
|
|
```nix
|
|
hyperhive.icon = ./icon.svg; # default: null (falls back to shared hyperhive logo)
|
|
```
|
|
|
|
Path to an SVG file used as this agent's visual identity — shown in
|
|
the per-agent page header, as the page favicon, and uploaded to the
|
|
agent's Forgejo profile avatar (via the `forge-avatar-sync` boot
|
|
unit) and Matrix profile avatar (set by `hive-matrix-daemon` over its
|
|
live Client). Commit the SVG next to `agent.nix` in the config repo
|
|
and reference it as a relative path.
|
|
|
|
When `null` (the default), the agent falls back to the shared
|
|
hyperhive branding mark. The harness serves whichever icon is active
|
|
at `GET /icon` on the per-agent web port.
|
|
|
|
## `user.passwordlessSudo`
|
|
|
|
```nix
|
|
hyperhive.user.passwordlessSudo = true; # default
|
|
```
|
|
|
|
Grants the per-agent unix user passwordless `sudo` (`NOPASSWD: ALL`).
|
|
Enabled by default so claude's shell tools work for operations that
|
|
need root inside the container (`systemctl`, package managers in dev
|
|
shells, etc.) — the same privilege surface the previous root-user shape
|
|
had, now elevated explicitly rather than implicitly.
|
|
|
|
Set to `false` for agents that should be strictly unprivileged.
|
|
Any tool invocation that needs root then fails loudly with the standard
|
|
sudo rejection rather than silently succeeding — easier to audit.
|
|
|
|
`hyperhive.user.uid`, `hyperhive.user.gid`, and
|
|
`hyperhive.user.name` are the companion options; see
|
|
`docs/agent-hierarchy.md` — "Harness systemd unit shape" for the full
|
|
`user.*` surface.
|
|
|
|
## Dashboard links
|
|
|
|
```nix
|
|
hyperhive.dashboardLinks = [
|
|
{ label = "Stats"; icon = "📊"; url = "http://localhost:9001/stats"; }
|
|
{ label = "Scratchpad"; url = "http://localhost:8080"; }
|
|
];
|
|
```
|
|
|
|
Declares extra navigation links that appear on the agent's dashboard
|
|
card and in the per-agent page header alongside the built-in forge /
|
|
config / container links. Each entry has:
|
|
|
|
| Field | Required | Description |
|
|
|-------|----------|-------------|
|
|
| `label` | yes | Display text shown in the icon strip tooltip and meta-nav. |
|
|
| `url` | yes | Absolute URL — may include a different port (the dashboard renders it as a plain anchor). |
|
|
| `icon` | no | Emoji or short glyph prefix. Defaults to empty string. |
|
|
|
|
The list is written to `<state>/hyperhive-dashboard-links.json` by a
|
|
one-shot systemd unit at container boot. `hive-c0re` reads the file on
|
|
each container-view snapshot and attaches the links to the agent card
|
|
(`kind = External`) without any code change. Omitting the option
|
|
(default empty) produces no extra links.
|
|
|
|
## Custom static files
|
|
|
|
```nix
|
|
hyperhive.frontend.extraFiles = {
|
|
"games/bitburner" = {
|
|
source = ./bitburner-dist; # path relative to agent.nix
|
|
# target defaults to attribute name: "games/bitburner"
|
|
};
|
|
"my-page" = {
|
|
source = ./my-page.html;
|
|
target = "my-page.html"; # explicit override
|
|
};
|
|
};
|
|
```
|
|
|
|
Layers additional files over the default per-agent web UI dist. Each
|
|
attribute defines one overlay entry:
|
|
|
|
- **`source`** — a Nix path (file or directory) copied into the merged
|
|
static tree. Evaluated at nix build time; the resulting derivation is
|
|
pointed at by `HIVE_STATIC_DIR`.
|
|
- **`target`** — destination path within the merged tree, used as both
|
|
the served URL prefix (`/<target>/…`) and the on-disk layout.
|
|
Defaults to the attribute name. Forward slashes create nested layouts
|
|
(`"games/bitburner"` serves at `/games/bitburner/…`).
|
|
|
|
Constraints: `target` must start with an alphanumeric or `_` and
|
|
contain only alphanumerics, `_`, `.`, `/`, `-`. `..` segments are
|
|
rejected by a config assertion. The merge step refuses to overwrite
|
|
files already present in the default dist — pick a target name that
|
|
does not collide with existing paths (`static/`, `index.html`, etc.).
|
|
|
|
The default dist ships at `hyperhive.frontend.dist` (the
|
|
`hyperhive-frontend` package output, read-only). To replace the
|
|
entire UI rather than layer on top, override `frontend.dist` directly.
|
|
|
|
## Connectivity overrides
|
|
|
|
Two `hyperhive.forge.*` / `hyperhive.matrix.*` options override where
|
|
the per-agent daemons connect. Both rarely need changing on a standard
|
|
single-host deploy, but are useful for multi-hive or custom-network
|
|
setups.
|
|
|
|
```nix
|
|
hyperhive.forge.url = "http://forge.example:3000"; # default: null
|
|
hyperhive.matrix.url = "https://matrix.example"; # default: null
|
|
```
|
|
|
|
**`hyperhive.forge.url`** — base URL of the Forgejo instance. Used by
|
|
a one-shot boot unit (`tea-login`) that writes `~/.config/tea/config.yml`
|
|
directly from the agent's `forge-token`, so `tea` and `hive-forge`
|
|
work without an interactive auth step. The unit is a no-op when
|
|
`forge-token` is absent. Override when the agent should connect to a
|
|
Forgejo on a different host or port (e.g. a swarm peer's forge).
|
|
Validated: must be an `http://` or `https://` URL, or `null`.
|
|
|
|
**Defaults to `null`, meaning "no forge" — not a guessed address.** A
|
|
loopback default would only ever be correct when the forge shares the
|
|
agent's network namespace, and inside a container `localhost` is the
|
|
agent itself, so the default was a value that built fine and then talked
|
|
to the wrong machine. With `null` the `tea-login` and `forge-avatar-sync`
|
|
units are not generated at all: an absent integration rather than a
|
|
misdirected one. You do not normally set this — hive-c0re renders the
|
|
host's real forge URL into every agent, and refuses to write a meta
|
|
flake without one, so `null` only survives where the agent modules are
|
|
evaluated outside a hive.
|
|
|
|
**`hyperhive.matrix.url`** — homeserver URL used by
|
|
`hive-matrix-daemon` when connecting via the matrix-sdk. hive-c0re
|
|
writes it into every agent at deploy time as the gateway-routed
|
|
`chat.<swarm-domain>` URL, so isolated agents can reach the homeserver.
|
|
Override per-agent when an agent should talk to a different homeserver
|
|
— for example a remote hive's tuwunel reached over a VPN, or an
|
|
external Matrix server for a federation-only agent.
|
|
|
|
**Defaults to `null`, meaning "no matrix" — for the same reason
|
|
`forge.url` does.** The homeserver may live on another host, and a
|
|
loopback default resolves inside the agent's own netns to the agent,
|
|
so it would be a value that evaluates fine and then talks to the wrong
|
|
machine. With `null` the daemon has no homeserver and no-ops exactly as
|
|
it does without a token. The hive only forwards `HIVE_MATRIX_URL` when
|
|
it actually has a matrix vhost to name, so `null` survives where a hive
|
|
runs no homeserver, or where the agent modules are evaluated outside a
|
|
hive.
|
|
|
|
## Claude Code plugins
|
|
|
|
The harness installs Claude Code plugins before the serve loop opens.
|
|
Two per-agent `agent.nix` options control this:
|
|
|
|
```nix
|
|
hyperhive.claudeMarketplaces = [ "anthropics/claude-plugins-official" ]; # default
|
|
hyperhive.claudePlugins = [ "skill-creator@claude-plugins-official" ]; # default
|
|
hyperhive.claudePluginsAutoUpdate = false; # default
|
|
```
|
|
|
|
- **`claudeMarketplaces`** — list of marketplace sources passed to
|
|
`claude plugin marketplace add <source>`. The official Anthropic
|
|
marketplace is pre-configured by default; override or extend to add
|
|
custom marketplaces. Idempotent — re-adding an existing source is
|
|
a no-op.
|
|
- **`claudePlugins`** — list of plugin specs passed to
|
|
`claude plugin install <spec>`. Each spec is installed on every boot
|
|
(`install` is expected to be idempotent); failures log a warning but
|
|
do not abort boot. Defaults to Anthropic's `skill-creator`, so every
|
|
agent can author, refine, and evaluate its own skills without any
|
|
per-agent wiring.
|
|
|
|
> Both plugin lists follow ordinary NixOS list-option semantics: a
|
|
> per-agent definition **replaces** the default, it does not extend it.
|
|
> An agent that sets `claudePlugins` and still wants `skill-creator`
|
|
> has to list it explicitly alongside its own entries — likewise for
|
|
> the official marketplace in `claudeMarketplaces`.
|
|
- **`claudePluginsAutoUpdate`** — when `true`, runs
|
|
`claude plugin marketplace update` before installing plugins to pull
|
|
the latest index. Disabled by default to keep boot times short and
|
|
plugin versions pinned.
|
|
|
|
## `cargo.shortMessages`
|
|
|
|
```nix
|
|
hyperhive.cargo.shortMessages = true; # default
|
|
```
|
|
|
|
When enabled (the default), the harness injects a `cargo` shell
|
|
function into `/etc/hyperhive/bash-env.sh` that transparently appends
|
|
`--message-format short` to compile subcommands (`build`, `check`,
|
|
`clippy`, `test`, `run`, `doc`, `bench`, `install`, `rustc`, `fix`).
|
|
This suppresses the per-crate progress lines that flood the response
|
|
window, leaving only warnings and errors.
|
|
|
|
The function handles `+toolchain` selectors (`cargo +nightly build`)
|
|
and passes through cleanly when `--message-format` is already present.
|
|
Non-compile subcommands (`new`, `add`, third-party `cargo-*`) are
|
|
left untouched.
|
|
|
|
Set to `false` for agents that parse cargo's JSON output
|
|
programmatically and do not pass `--message-format json` themselves.
|
|
|