# 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`). 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/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/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: static shell + /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 assets/ index.html, dashboard.css, app.js (include_str!) hive-fr0nt/ shared frontend-assets crate (browser only). src/lib.rs pub const BASE_CSS / TERMINAL_CSS / TERMINAL_JS / MARKED_JS re-exports; both binaries `include_str!` them and prepend to their per- page serving routes. assets/base.css Catppuccin palette + body typography (one source of truth, no per-page redeclaration). assets/terminal.css `.terminal-wrap` + `.live` + `.tail-pill` + `.row` / `details.row` styling for both pages' lit log panes. Unified prefix-column (padding-left + negative text-indent) so glyph alignment is consistent across row kinds + a `.md` block scope for marked-rendered bodies. assets/terminal.js `window.HiveTerminal.create(opts)`: scroll- sticky log + "↓ N new" pill + history backfill + SSE subscribe-buffer-snapshot- dedupe dance. Pages register a kind→renderer map; the terminal owns the lifecycle. assets/marked.umd.js vendored marked v4.0.2 UMD bundle. Per-agent terminal uses the global `marked.parse` for markdown bodies on send / recv / ask / answer / assistant text rows. 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) assets/ index.html, agent.css, app.js, stats.html, stats.js, screen.html (include_str!) 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-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 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.