174876094e
Add docs/observability.md covering all services.hyperhive.otel.*
options: enable, endpoint, protocol, headersCredential,
extraResourceAttributes, debug (new in cb0a66147a), and
metricIntervalMs.
Includes:
- Built-in OTEL_RESOURCE_ATTRIBUTES labels (service.name, agent, hive, swarm)
- Cumulative temporality note (avoids Prometheus DELTA drop)
- Network note for host-side collectors on non-standard ports,
cross-referencing docs/network.md exposeHostPorts
Also:
- CLAUDE.md: add reading-path entry for the new doc
- docs/network.md: link the OTEL mention to observability.md
Closes no issue — gap found during doc sweep.
131 lines
6.6 KiB
Markdown
131 lines
6.6 KiB
Markdown
# hyperhive — claude entry point
|
|
|
|
Hey claude. This is your starting page. The detailed docs live in
|
|
[`docs/`](docs/) and are written for humans + you both — read them
|
|
when you need depth on a subsystem. This file is the index.
|
|
|
|
- High-level project intro: **[README.md](README.md)**.
|
|
- Open work + backlog: the **[forge issue
|
|
tracker](http://localhost:3000/hyperhive/hyperhive/issues)**.
|
|
- Operator/agent trust-boundary design:
|
|
**[docs/boundary.md](docs/boundary.md)** (`area:ops` issues
|
|
for the deployment/gateway/privsep work).
|
|
- Agent trust model (trust boundary, prompt-injection threat model,
|
|
capability = accepted risk), credential isolation + sandbox threat model:
|
|
**[docs/security.md](docs/security.md)**.
|
|
|
|
## Repo map
|
|
|
|
One line per crate / top-level dir. **Each module's authoritative,
|
|
always-current description lives in its own `//!` doc-comment** —
|
|
`grep`/read the module when you need detail. This index is kept
|
|
deliberately lean: it auto-loads into every turn's context, and a
|
|
hand-maintained per-file tree drifts out of sync with the code.
|
|
|
|
### Rust workspace (`Cargo.toml` members)
|
|
|
|
- **`hive-c0re/`** — host daemon (runs as the unprivileged `hive-core`
|
|
user) plus two operator CLIs. `src/main.rs` is the `hive-c0re` binary
|
|
(serve / spawn / kill / rebuild / approve / destroy / periodic vacuum
|
|
loops); `src/bin/hivectl.rs` is the ad-hoc operator admin CLI. Owns
|
|
the sqlite broker, approval + question + reminder + schedule queues,
|
|
the meta flake, lifecycle (`nixos-container` shellouts), gateway /
|
|
forge / matrix provisioning, per-container stats, and the axum
|
|
operator dashboard (`dashboard.rs`). Largest crate.
|
|
- **`hive-ag3nt/`** — in-container harness; one `hive` binary for every
|
|
agent. Turn loop (`turn.rs`), embedded MCP server (`mcp.rs`), per-agent
|
|
web UI (`web_ui.rs`), event + turn-stats sqlite sinks, login flow,
|
|
system-prompt renderer, forge-notify subscriber.
|
|
- **`hive-priv/`** — minimal root privileged-helper, socket-activated at
|
|
`/run/hive/priv.sock`; performs the few root operations (bind-mount
|
|
edits, nsenter) the unprivileged `hive-c0re` delegates to it. See
|
|
`docs/boundary.md`.
|
|
- **`hive-forge/`** — `hive-forge` Forgejo CLI wrapper; one module per
|
|
verb under `src/verbs/`.
|
|
- **`hive-matrix-mcp/`** — per-agent matrix-sdk daemon plus the thin
|
|
stdio MCP bridge claude spawns per turn.
|
|
- **`hive-bash-mcp/`** — per-agent bash-task runner daemon plus its
|
|
stdio MCP bridge; writes task files under `/harness/bash-tasks/` and
|
|
the favorite-tools `bash_commands` stat into turn-stats.sqlite.
|
|
- **`hive-sh4re/`** — shared wire types (Host / Agent / Manager request
|
|
+ response, `Message`, `Approval`, `HelperEvent`) used across the
|
|
unix sockets.
|
|
|
|
### Other top-level dirs
|
|
|
|
- **`frontend/`** — npm workspaces → static dashboard + per-agent UI
|
|
dist, built hermetically by `nix/frontend.nix`. Packages: `shared`
|
|
(terminal pane + Catppuccin palette), `dashboard` (the operator SPA),
|
|
`agent` (the default per-container UI).
|
|
- **`nix/`** — NixOS modules (`modules/hive-{c0re,forge,gateway,matrix,
|
|
ci,network}.nix`) + per-container templates (`templates/{harness-base,
|
|
agent-base,manager,weston-vnc}.nix`) + the options-doc derivation.
|
|
- **`docs/`** — subsystem reference docs (see *Reading paths* below).
|
|
- **`branding/`**, **`scripts/`** — static assets + helper scripts.
|
|
|
|
## Reading paths
|
|
|
|
Pick the doc that matches your task. None depend on the others —
|
|
read them à la carte.
|
|
|
|
- **"How do I bring a fresh hive online (first-run hivectl
|
|
bootstrap)?"** → [`docs/setup.md`](docs/setup.md).
|
|
- **"What does the dashboard look like?"** →
|
|
[`docs/web-ui.md`](docs/web-ui.md) (index; sub-pages:
|
|
[`shape`](docs/web-ui/shape.md),
|
|
[`dashboard`](docs/web-ui/dashboard.md),
|
|
[`agent`](docs/web-ui/agent.md)).
|
|
- **"How does the per-agent terminal classify + colour
|
|
events?"** → [`docs/terminal-rendering.md`](docs/terminal-rendering.md).
|
|
- **"How does claude get its prompt and what tools does it have?"** →
|
|
[`docs/turn-loop.md`](docs/turn-loop.md).
|
|
- **"How do config changes flow from manager to operator to
|
|
container?"** → [`docs/approvals.md`](docs/approvals.md).
|
|
- **"What state survives destroy / purge / restart?"** →
|
|
[`docs/persistence.md`](docs/persistence.md).
|
|
- **"Naming, commit style, wire protocol, the `data-async`
|
|
pattern."** → [`docs/conventions.md`](docs/conventions.md).
|
|
- **"Why does the nspawn flag look like that?"** →
|
|
[`docs/gotchas.md`](docs/gotchas.md).
|
|
- **"What nginx vhosts does the gateway serve? How does matrix
|
|
discovery work?"** → [`docs/gateway.md`](docs/gateway.md).
|
|
- **"How do per-agent forge accounts work? What does forge_notify
|
|
poll + how does it format wake messages?"** →
|
|
[`docs/forge.md`](docs/forge.md).
|
|
- **"What verbs does `hive-forge` support? How do I post a comment,
|
|
upload an attachment, manage subscriptions?"** →
|
|
[`docs/tools/forge.md`](docs/tools/forge.md).
|
|
- **"What does `hivectl` do? How do I provision a forge/matrix account,
|
|
manage gateway users, restart containers, or drop into an agent shell?"** →
|
|
[`docs/tools/hivectl.md`](docs/tools/hivectl.md).
|
|
- **"How does the matrix-tuwunel container work? What about
|
|
fluffychat-web and per-agent matrix accounts?"** →
|
|
[`docs/matrix.md`](docs/matrix.md).
|
|
- **"How does DNS resolution work in agent containers? What's the
|
|
bridge network for?"** → [`docs/network.md`](docs/network.md).
|
|
- **"How do I connect two hives into a swarm? How do I declare peer
|
|
hives and configure TLS trust?"** →
|
|
[`docs/swarm.md`](docs/swarm.md).
|
|
- **"How does the rebuild queue work? What are queue kinds and sources?"** →
|
|
[`docs/coordinator.md`](docs/coordinator.md).
|
|
- **"How does the CI runner work? What's the auto-registration flow?"** →
|
|
[`docs/ci.md`](docs/ci.md).
|
|
- **"What is `/knowledge`? How does the hive-wide knowledge repo sync,
|
|
and how do I contribute a document?"** →
|
|
[`docs/knowledge.md`](docs/knowledge.md).
|
|
- **"How do I export Claude Code metrics (tokens, cost, tool calls) to
|
|
a Prometheus/Grafana collector? What OTEL options are available?"** →
|
|
[`docs/observability.md`](docs/observability.md).
|
|
|
|
## Conventions & process
|
|
|
|
The docs below own the details — this section just points at them.
|
|
|
|
- **Commit style, naming, identity, reconcile verb:** →
|
|
[`docs/conventions.md`](docs/conventions.md).
|
|
- **NixOS / nspawn quirks** (bind mounts, conf flags, etc.): →
|
|
[`docs/gotchas.md`](docs/gotchas.md).
|
|
- **Turn loop, sentinels (rate-limit, auth-failed), context
|
|
window:** → [`docs/turn-loop.md`](docs/turn-loop.md).
|
|
- **Two-step spawn, approval flow, flake.lock validation:** →
|
|
[`docs/approvals.md`](docs/approvals.md).
|