vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hyperhive/hive-c0re/README.md

4.7 KiB
Raw Blame History

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.