89 lines
4.7 KiB
Markdown
89 lines
4.7 KiB
Markdown
# hive-c0re
|
|
|
|
The unprivileged host daemon (runs as `hive-core`). This is the biggest
|
|
crate in the workspace — it owns the sqlite broker, the approval /
|
|
question / reminder / schedule queues, the generic job-DAG queue,
|
|
lifecycle (`nixos-container` shellouts + per-agent flake generation),
|
|
gateway/forge/matrix provisioning, per-container stats, and the axum
|
|
operator dashboard.
|
|
|
|
`hive-c0re` is **bin-only**: this binary owns the whole module tree
|
|
directly (no separate lib crate). The operator CLI used to live here
|
|
too, but moved out to the standalone `hivectl` crate, which talks to
|
|
this daemon over the host admin socket instead of linking it.
|
|
|
|
## When to use it
|
|
|
|
This is where host-level, cross-container orchestration logic lives:
|
|
spawning/rebuilding/destroying agent containers, approving config
|
|
changes, reconciling desired vs. actual container state, provisioning
|
|
per-agent forge/matrix/gateway accounts, and serving the dashboard.
|
|
If you're changing what the operator sees on the dashboard, how a
|
|
container gets spawned or torn down, or anything in the approval flow,
|
|
it's here. Agent-side behavior (the turn loop, MCP tools) lives in
|
|
`hive-agent`/`hive-agent-mcp` instead — this daemon only talks to
|
|
agents over the unix socket wire types in `hive-sh4re`.
|
|
|
|
## Shape
|
|
|
|
Cohesive clusters live in directory submodules; each child is
|
|
re-exported at the crate root so `crate::broker::…`-style paths keep
|
|
resolving unchanged regardless of which subdirectory a module actually
|
|
lives in.
|
|
|
|
- **`dashboard/`** — the axum operator dashboard: managed containers
|
|
(with deep-links to each container's own web UI), pending approvals
|
|
(unified diff vs. the applied repo + approve/deny), schedules,
|
|
questions, journal/build-log viewers, topology, webhook ingest.
|
|
- **`job_queue/`** — generic job-DAG queue + desired-state
|
|
reconciliation, the host-side wrapper over the domain-agnostic
|
|
`hive_jobq` scheduler. Jobs are nodes in per-request DAGs
|
|
(`templates.rs`); special cases (graceful-stop watcher, deferred-start
|
|
follow-up, meta-update cascade, topology reparents) collapse into DAG
|
|
*shapes* over the shared node primitives (`model::NodeKind`). See
|
|
`docs/coordinator.md`.
|
|
- **`lifecycle/`** — `nixos-container` lifecycle (spawn/kill/destroy/
|
|
rebuild/restart) + per-agent config flake generation.
|
|
- **`stores/`** — sqlite-backed host-side stores: the broker
|
|
(`broker.rs`), approval / question / schedule queues, build logs,
|
|
audit trail, power intent, plus the shared connection open/migration
|
|
helper (`db.rs`).
|
|
- **`workers/`** — background tasks and periodic sweeps: crash/login
|
|
watcher, scheduled-prompt delivery loop, boot-time auto-update
|
|
reconcile, the agent-sockets.json writer loop, the MCP socket
|
|
listener reconcile loop, knowledge-repo sync.
|
|
- **`agent_config/`** — per-agent configuration registries (tool
|
|
groups, capabilities, resource limits, topology — all JSON under
|
|
`/var/lib/hyperhive/meta/`) plus the shared wire-protocol size
|
|
limits. Note the two similarly-named modules: `limits` caps inline
|
|
message-body sizes on the sockets, while `resource_limits` holds
|
|
per-agent CPU/memory caps for the container drop-in (`agentMemoryMax`
|
|
etc.).
|
|
- **`stats/`** — metrics aggregation for the dashboard: hive-wide
|
|
turn-stats rollups, host-system probes/server warnings, live
|
|
per-container cgroup load, OTEL metric export.
|
|
- **`socket_server/`** — the unix-socket request server, shared by the
|
|
per-agent sockets and the (pure-transport) manager socket. The socket
|
|
file's existence on disk authenticates the caller — connecting to
|
|
`<.../agents/foo/mcp.sock>` means you are `foo`. No privilege flag:
|
|
authority derives from the caller's identity (topology, capabilities,
|
|
tool-group membership), not a hardcoded name match.
|
|
- **`forge/`** — optional Forgejo wiring: per-agent user + token
|
|
provisioning, config-repo mirroring, meta read-access grants, the CI
|
|
runner registration, PR auto-merge. No-op when `hive-forge` (the
|
|
container) isn't running. Full design: `docs/forge.md`.
|
|
- **`coordinator.rs`** — top-level `Coordinator`/`HiveEnv`/`ServeConfig`
|
|
wiring that ties the above together for `serve`.
|
|
- **`meta.rs`**, **`migrate.rs`** — the meta flake (agent config repos)
|
|
and schema/state migrations.
|
|
- **`matrix.rs`**, **`gateway_nginx.rs`**, **`webhook_secret.rs`** —
|
|
matrix provisioning, gateway nginx vhost rendering, webhook secret
|
|
management.
|
|
- **`priv_client.rs`** — client for the `hive-priv` privileged-helper
|
|
socket (the few root operations this unprivileged daemon delegates
|
|
out — see `docs/boundary.md`).
|
|
|
|
`src/main.rs` is the `hive-c0re` binary entry point: `serve` (the
|
|
daemon) plus the periodic vacuum/sweep loops. See the top-level
|
|
`CLAUDE.md`/`docs/` index for the full reading-path map — this README
|
|
is just the module tour.
|