| Filename | Latest commit message | Latest commit date |
|---|---|---|
461c599e09
Third batch of hyperhive#4042's Passive pass (see #4098/#4099 for the
first two and the read-every-hit discipline this pass uses). 23 hits
across boundary.md (10) and security.md (13).
boundary.md, 2 of 10 rewritten:
- "Operator-authority actions ... are served by the core daemon and
only reachable via the gateway" -> "The core daemon serves
operator-authority actions ..., reachable only via the gateway" --
the actor was already named in the sentence, and the parallel
"Agent" bullet right below it is already active voice ("speaks only
for itself"), so the Operator bullet was the inconsistent one.
- "ownership set afterwards is reverted the next time any agent
changes" -> "and reverts any ownership set afterwards the next time
any agent changes" -- continues the same subject ("the `d`
re-applies ... and reverts ...") already established one clause
earlier, avoiding a subject switch entirely.
security.md, 6 of 13 rewritten (across 3 edits touching 6 flagged
locations):
- "A compromised/confused agent's reach ... is bounded by its own
account's scope" -> "Its own account's scope bounds a
compromised/confused agent's reach" -- matches the section's own
header ("Scoped tokens bound the blast radius"), which is already
active voice.
- "Two allow-listed root prefixes are accepted; all other paths are
rejected" -> "It accepts two allow-listed root prefixes and rejects
all other paths" -- continues "it" from the endpoint named one
sentence earlier.
- The container-allowlist paragraph (3 flagged locations: "is
validated", "are accepted", "are rejected") rewritten as one
consistent-subject passage with `hive-priv` as the actor throughout,
matching the neighboring bullets in the same subsection
("**Socket-activated** -- systemd starts hive-priv...", already
active voice) -- the passive version was the odd one out among
siblings, not the house style.
15 of 23 hits left alone. The recurring legitimate shapes, same
categories as #4098: predicate-adjective copulas that only look like
passives ("an agent is trusted code", "the agent is privileged" --
"trusted"/"privileged" modify the noun, there's no actor to name),
quoted rhetorical contrasts where the passive is doing real work (a
"wrong-framing" quote left passive on purpose, paired with an active
"right-framing" quote right after it), the "is tracked as/in X"
idiom (twice, same as #4098's precedent), and "X can't be Yed" /
negative-capability invariant statements (matches #4098's "No X is Y"
security-guarantee idiom). One deliberately left despite a nameable
antecedent ("hive-gateway's access is scoped [by ReloadGatewayNginx]
instead") -- lower-confidence rewrite than the others, left rather
than force it.
Verified: vale docs/trust-boundary before/after -- 23 -> 15
write-good.Passive hits, exactly the 8 rewritten, no other rule's hit
count moved (the TooWordy/Microsoft.Avoid/alex hits vale also reports
on these two files are pre-existing and out of scope for a
Passive-only pass; TooWordy's hits specifically already have a fix
queued in #4097, not duplicated here).
|
||
| .. | ||
| agent-lifecycle | ||
| crates | ||
| getting-started | ||
| integrations | ||
| networking | ||
| process | ||
| scheduler | ||
| swarm | ||
| tools | ||
| trust-boundary | ||
| turn-loop | ||
| web-ui | ||
| README.md | ||
hyperhive docs
Depth reference for hyperhive — the substrate, not the pitch (that's the
top-level README / website).
Every page here stands alone; pick the one matching your task rather than
reading top to bottom. For the autogenerated NixOS options reference
(every services.hyperhive.* / hyperhive.* option, host and agent), see
the options site instead —
this tree is prose, that one's generated straight from the module
declarations.
Getting started
- Bringing a fresh hive online? →
getting-started/setup.md(first-runhivectlbootstrap). - What does the dashboard look like, and how do I use it? →
web-ui/— the operator-facing starting point; its own sub-pages (shape,dashboard,agent,css-vars,terminal-rendering) go deeper into implementation. - What tools does an agent (or the operator) have available? →
tools/—hivectl(yours) plus every agent's MCP tool surface (bash, forge, lifecycle, matrix, scheduling).
Agent lifecycle
- How do config changes flow from manager to operator to container? →
agent-lifecycle/approvals.md(two-step spawn, approval state machine,flake.lockvalidation). - What state survives destroy / purge / restart? →
agent-lifecycle/persistence.md. - Who can do what to whom — agent hierarchy and privilege? →
agent-lifecycle/agent-hierarchy.md. - How does claude get its prompt, and what tools does it have? →
turn-loop/— the loop, binary shape, turn outcomes; sub-pages:claude-invocation,config,mcp.
Trust boundary & security
- What's the operator/agent trust boundary? What's a capability? →
trust-boundary/boundary.md. - Agent trust model, prompt-injection threat model, credential
isolation? →
trust-boundary/security.md.
Accounts & integrations
- How do per-agent forge accounts work? What does
forge_notifypoll, and how does it format wake messages? →integrations/forge.md(the hive's own Forgejo);tools/forge.mdfor thehive-forgeCLI verbs agents actually call. - How does the matrix-tuwunel container work? Multiple accounts per
agent? →
integrations/matrix.md(the homeserver);tools/matrix.mdfor the MCP tool surface andhyperhive.matrixAccounts. - How do I give an agent a GitHub account (
gh+git push)? how's the PAT injected? →integrations/github.md(operator content up top; thegh/git-push + notification-poller mechanics are in a collapsed "Implementation" section at the bottom). - What's
/knowledge? How does the hive-wide knowledge repo sync, and how do I contribute a document? →integrations/knowledge.md. - What does
hivectldo? Provisioning, gateway users, container shells? →tools/hivectl.md(the curated guide);tools/hivectl-cli.mdfor the exhaustive, autogenerated flag reference.
Networking & swarms
- What nginx vhosts does the gateway serve? How does matrix
discovery work? →
networking/gateway.md. - How does DNS resolution work in agent containers? What's the
bridge network for? →
networking/network.md. - How do I connect two hives into a swarm? →
swarm/(peer hives, TLS trust). - Where do agent snapshots go? How does the swarm's
btrfs receiveendpoint authenticate a pushing hive? →networking/snapshot-store.md.
Scheduler, CI, observability
- what's the job queue, as a general idea (not hive-c0re specifics)? →
scheduler/jobq.md— operator-facing, no implementation detail. - How does the rebuild queue work? What are the concrete step kinds,
queue sources, scheduler internals? →
scheduler/coordinator.md. - How does the CI runner work? What's the autoregistration flow? →
scheduler/ci.md. - How do I export Claude Code metrics (tokens, cost, tool calls) to
Prometheus/Grafana? →
scheduler/observability.md.
Crate reference
- What does a specific Rust crate do, on its own terms? →
crates/— every workspace crate's ownREADME.md, one level up from source (hyperhive#3051); the crate itself is still the source of truth, this is just a walkable mirror.
Process & conventions
- Naming, commit style, wire protocol, the
data-asyncpattern? →process/conventions.md. - Why does the nspawn flag look like that? →
process/gotchas.md(bind mounts, conf flags, other NixOS/nspawn quirks). - What does a PR review verdict actually gate? →
process/pr-review-gate.md.