# hive-c0re

The unprivileged host daemon (runs as `hive-core`). Owns the sqlite
broker, the approval/question/schedule queues, the generic job-DAG
queue, container lifecycle, gateway/forge/matrix provisioning,
per-container stats, and the axum operator dashboard. Largest crate in
the workspace — bin-only, no separate lib.

## When to use it

Host-level, cross-container orchestration: spawning/rebuilding/
destroying agent containers, the approval flow, dashboard-visible
state, provisioning per-agent forge/matrix/gateway accounts. Agent-side
behavior (turn loop, MCP tools) lives in `hive-agent`/`hive-agent-mcp`
instead — this daemon only talks to agents over the socket wire types
in `hive-sh4re`.

## Shape

Cohesive clusters live in directory submodules, each re-exported at
the crate root (`crate::broker::…` keeps resolving regardless of which
subdirectory a module actually lives in). One line each — read the
module's own `//!` doc-comment for real detail, don't expect this file
to track it:

- **`dashboard/`** — the operator dashboard (containers, approvals,
  schedules, questions, logs, topology).
- **`job_queue/`** — the job-DAG queue + desired-state reconciliation
  (`docs/coordinator.md`).
- **`lifecycle/`** — `nixos-container` lifecycle + per-agent config
  flake generation.
- **`stores/`** — sqlite-backed stores (broker, queues, audit, power).
- **`workers/`** — background sweeps (crash watch, scheduled prompts,
  auto-update, knowledge sync).
- **`agent_config/`** — per-agent registries (tool groups,
  capabilities, resource limits, topology).
- **`stats/`** — dashboard metrics aggregation + OTEL export.
- **`socket_server/`** — the unix-socket request server shared by
  per-agent + manager sockets.
- **`forge/`** — optional Forgejo wiring (`docs/forge.md`).
- **`coordinator.rs`** — top-level wiring for `serve`.
- **`meta.rs`**, **`migrate.rs`** — the meta flake + schema/state
  migrations.
- **`matrix.rs`**, **`gateway_nginx.rs`**, **`webhook_secret.rs`**,
  **`priv_client.rs`** — matrix provisioning, gateway vhosts, webhook
  secrets, and the `hive-priv` client respectively.

See the top-level `CLAUDE.md`/`docs/` index for the full reading-path
map.