# 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). - Credential isolation + sandbox threat model: **[docs/security.md](docs/security.md)**. ## File map ``` hive-c0re/ host daemon + CLI (one binary, subcommand-dispatched) src/main.rs clap setup; serve / spawn / kill / rebuild / list / pending / approve / deny / destroy [--purge] / request-spawn; periodic vacuum tasks src/server.rs host admin socket (HostRequest → dispatch) src/client.rs admin-socket client src/manager_server.rs manager-privileged socket (ManagerRequest) src/agent_server.rs per-sub-agent socket listener (long-poll Recv) src/broker.rs sqlite Message store + intra-process broadcast channel (`MessageEvent`) for `recv_blocking_batch` + the dashboard forwarder; hourly vacuum of acked>30d src/dashboard_events.rs unified wire-facing event channel feeding `/dashboard/stream`. Carries broker `Sent` / `Delivered` (mirrored by the forwarder task in main.rs) + mutation events (`ApprovalAdded` / `ApprovalResolved`, `QuestionAdded` / `QuestionResolved`, `TransientSet` / `TransientCleared`, `RebuildQueueChanged`). Each frame carries a monotonic per-process `seq` clients use to dedupe against snapshot reads. src/approvals.rs sqlite Approval queue + kinds src/operator_questions.rs sqlite question queue backing `ask` / `answer` (both operator + agent-to-agent) src/questions.rs shared dispatch for `Ask` / `Answer` — used by both agent + manager surfaces src/reminder_scheduler.rs 5s poll loop: drains due reminders, resolves file_path container→host, persists payload + delivers pointer string src/events_vacuum.rs host-side hourly sweep of every agent's /state/hyperhive-events.sqlite src/crash_watch.rs poll every 10s; fire HelperEvent::ContainerCrash when a previously-running container disappears without an operator-initiated transient src/container_view.rs ContainerView struct + build_all helper; shared between dashboard.rs (cold-load via /api/state) and coordinator.rs's rescan_containers_and_emit src/coordinator.rs shared state (broker/approvals/operator_questions/ transient/sockets) + tombstone enumeration + kick_agent + notify_agent (helper-event push) + last_containers cache + rescan_and_emit diff helper src/loose_ends.rs loose-ends aggregator (pending approvals + unanswered questions + pending reminders) — for_agent (filtered) and hive_wide (manager surface). Backs AgentRequest::GetLooseEnds + ManagerRequest::GetLooseEnds (the get_loose_ends MCP tool). src/rebuild_queue.rs global serialised queue for long-running ops (rebuild / meta_update / spawn / destroy). Single background worker drains FIFO; dedup collapses re-enqueued still-queued entries. `QueueEntry` carries id, agent, kind, state, source, parent_id (cascade grouping), timing, reason, error. Emits `RebuildQueueChanged` snapshots on every mutation. src/actions.rs approve/deny/destroy (transient-aware) src/auto_update.rs startup rebuild scan + ensure_manager + meta::lock_update_hyperhive bump src/lifecycle.rs `nixos-container` shellouts; per-agent applied + proposed git repo seeding; tag plumbing src/meta.rs single hive-c0re-owned flake at /var/lib/ hyperhive/meta/ — sync_agents, two-phase prepare/finalize/abort, lock_update_* src/migrate.rs startup auto-migration from pre-meta layout (idempotent, marker-guarded phase 4) src/topology.rs agent parent/child storage at /var/lib/hyperhive/meta/topology.json — sole source of truth for who's the parent of whom (single source the dashboard, render_flake, and the eventual cap-enforcement plumbing all read). Reconciled by `meta::sync_agents`; operator/manager edits land via the eventual write API (#361 follow-ups). src/forge.rs optional Forgejo wiring: per-agent users + tokens, the `agent-configs` org (`push_config`), and meta read access; mirrors each applied repo into `agent-configs/` (core-only); agents are read-only collaborators on `core/meta` src/dashboard.rs axum HTTP: /api/state JSON + actions + journald viewer + bind-with-retry (SO_REUSEADDR) + deployed_sha chip per container + /dashboard/{stream,history} subscribing to the unified DashboardEvent channel. Static assets (HTML/CSS/JS/favicon) served by tower_http::ServeDir from $HIVE_STATIC_DIR (= `${frontend}/dashboard` per the c0re module). frontend/ npm workspaces (esbuild → static dist). Built hermetically by `nix/frontend.nix` (`packages.${system}.frontend`). packages/shared/ @hive/shared: terminal pane + Catppuccin palette + base typography (was hive-fr0nt). ES module exporting { create, linkify }; pure JS, no IIFE globals; consumed by dashboard + agent. packages/dashboard/ @hive/dashboard SPA: src/{index.html, app.js, dashboard.css} + build.mjs → dist/{index.html, static/{app.js, dashboard.css}}. packages/agent/ @hive/agent default per-container UI: src/ {index, stats, screen}.html + {app, stats}.js + agent.css → dist/{*.html, static/*}. hive-ag3nt/ in-container harness crate; produces TWO binaries src/lib.rs re-exports + DEFAULT_SOCKET, DEFAULT_WEB_PORT src/client.rs generic JSON-line request/response over unix socket src/web_ui.rs per-container axum HTTP page (incl /api/cancel, /api/compact, /api/model, /events/history, /screen, /screen/ws) src/turn_stats.rs per-turn analytics sink (one sqlite row per turn at /state/hyperhive-turn-stats.sqlite); schema + best-effort writer src/stats.rs read-side aggregations over turn-stats.sqlite backing the /stats page (bucketed Snapshot: turns / duration / tokens / model mix) src/events.rs LiveEvent + broadcast Bus + sqlite-backed history (/state/hyperhive-events.sqlite) + TurnState + model selection (persisted at /state/hyperhive-model) src/turn.rs claude --print + stream-json pump; --compact retry; proactive compaction + auto session-reset src/mcp.rs embedded MCP server (rmcp): AgentServer + ManagerServer src/login.rs probe /root/.claude/ for a valid session src/login_session.rs drives `claude auth login` over stdio pipes src/bin/hive-ag3nt.rs sub-agent main (Serve + Mcp subcommands) src/bin/hive-m1nd.rs manager main (Serve + Mcp subcommands) Static UI assets served by ServeDir from $HIVE_STATIC_DIR (= hyperhive.frontend .mergedDist — default agent dist + per-agent extraFiles, set per the harness-base module). prompts/ static role/tools/settings for claude (include_str!): agent.md — sub-agent system prompt manager.md — manager system prompt claude-settings.json — --settings JSON hive-forge/ Forgejo CLI wrapper (`hive-forge` binary) src/main.rs clap dispatch over the verbs/ src/client.rs blocking reqwest client (Forgejo REST API) src/body.rs body input resolution (--body / --body-file / piped stdin) src/verbs/.rs one module per verb (view, issue, pr, comment, comment-show, comment-edit, issue-create, issue-edit, pr-create, pr-reviews, assign, close, labels, milestone, branches, tree-sha, diff, subscription, attach-issue, attach-comment). Replaces the 600-line hive-forge-tools.nix bash script (closes #280). hive-sh4re/ wire types (HostRequest/Response, AgentRequest/Response, ManagerRequest/Response, Message, Approval, HelperEvent) nix/ modules/hive-c0re.nix systemd service + firewall + git wiring; `contextWindowTokens` attrset (per-model, injected as env vars into all containers); imports hive-forge.nix modules/hive-forge.nix optional in-container Forgejo (`hyperhive.forge.enable`, default on); Catppuccin Mocha theme via tmpfiles C+ copy templates/harness-base.nix shared scaffolding for sub-agents + manager; `hyperhive.model` option (HIVE_DEFAULT_MODEL) templates/agent-base.nix sub-agent nixosConfiguration templates/manager.nix manager nixosConfiguration templates/weston-vnc.nix optional `hyperhive.gui.enable` — weston + VNC backend systemd unit; writes /etc/hyperhive/gui.json (vnc_port + auth) for the harness WebSocket relay (/screen/ws) forge-theme/theme-catppuccin-vibec0re.css Catppuccin Mocha forge theme docs/ conventions.md naming, identity=socket, async forms, commit style gotchas.md NixOS / nspawn quirks and lessons learned web-ui.md dashboard + per-agent page layouts and endpoints turn-loop.md claude invocation, wake prompt, MCP tool surface approvals.md approval flow, manager policy, helper events persistence.md sqlite dbs, retention, state dir layout terminal-rendering.md per-agent terminal row taxonomy (as built) boundary.md operator/agent trust model rationale agent-hierarchy.md tree-shape topology design + manager-privilege audit (#361) damocles-migration.md future migration plan for damocles → hyperhive ``` ## Reading paths Pick the doc that matches your task. None depend on the others — read them à la carte. - **"What does the dashboard look like?"** → [`docs/web-ui.md`](docs/web-ui.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). ## Quick reminders - **Commit before test.** Stage and commit when work *looks* ready, then run validation. Failures get a follow-up commit rather than an amend. - **Commit messages: short, lowercase, no `Co-Authored-By` trailer.** Imperative mood. - **`rebuild` is the reconcile verb.** Anything that changes per-container state on the host should be re-applied there so the dashboard's `↻ R3BU1LD` is sufficient to recover. - **Identity = socket.** No auth tokens — the socket path identifies the principal. - **Actions are factored** between admin socket and dashboard via `actions.rs` and `dashboard.rs::lifecycle_action`, so the two surfaces never drift. - **Two-step spawn:** `request_init_config` → edit `agent.nix` → `request_apply_commit`. The first apply_commit creates the container; subsequent ones rebuild it. `request_spawn` still works but is deprecated. - **Rate-limit sentinel:** `{state_dir}/hyperhive-rate-limited` is written by the harness on 429 and cleared on retry. `ContainerView.rate_limited` reads it for the dashboard badge. - **Context window:** defaults are in `services.hive-c0re.contextWindowTokens` (host nix, affects all agents). Per-agent default model via `hyperhive.model` in `agent.nix`. Watermarks are 75%/50% of the effective window.