Compose a PRView SourceOpen Issue

Synced from Hive. This page is pulled from kubestellar/hive@v4 during the docs build. Edit the canonical source in the Hive repository.

Hive documentation

Documentation for the current Hive line (branch v4; the code and docs live under the src/ directory). The v2 branch was retired in August 2026 — operators upgrading a v2 deployment should start with the v2 → v4 migration guide.

Start with Architecture for the system overview, then use the topic guides below. New users should start with the getting-started guide — it covers setting up the Forge App (the app for your source control system, e.g., GitHub, GitHub Enterprise, GitLab, or Gitea) and what to do if an inactive hosted hive is reaped.

Operations

  • Manual provisioning — heartbeat-only cluster provisioning, hub access roles, and common gotchas.
  • Self-hosted hub deployment — HIVE_MODE=hub, hub storage, heartbeat secrets, and SaaS spoke registration.
  • CAP_NET_ADMIN and self-hosted spokes — the container runs with or without NET_ADMIN; granting it (--cap-add NET_ADMIN / securityContext.capabilities.add) enables the full forced-proxy-egress gate, and what the degraded best-effort mode means without it.
  • Config layering — how ConfigMap seed, PVC dashboard overlay, and runtime config interact.
  • Operator reference — top-level config blocks, hive flags/env, GitHub token scopes, and image provenance.
  • Token mint — the opt-in mint: block (pkg/mint): what a minted token grants, key lifecycle, and the trust boundary an operator must get right before enabling it. Companion to ADR-0007.
  • Changelog — recent user-visible changes and release notes.
  • Release channels — stable/candidate/edge moving image tags, switching a hive to a channel, and the stable (v4) version pill.
  • Tagged releases — the automated v1.2.3 release path: what triggers a release, how the version is inferred from CHANGELOG.md, the commit convention that drives it, the human escape hatch, how it relates to the moving release channels above, and the per-release SPDX SBOM attached to each GitHub Release (and why it is a release artifact, not an in-image attestation — see #3760).
  • The auto-update Compose profile — what unattended Watchtower updates cost you, what the Docker socket proxy does and does not fix, and why Kubernetes should not use this profile at all.
  • Environment variable reference — centralized list of runtime, deployment, hub, backup, and contributor environment variables.
  • Kubernetes deployment — the operator path for Kubernetes: prerequisites, namespace, secret, ConfigMap, PVC, Deployment, Service, Ingress, and published ports. Lives in the root README alongside the Compose and Podman quick starts; the manifests it applies are src/deploy/k8s/. See also dashboard route and health checks and the Kubernetes CronJob in backup and restore.
  • Troubleshooting — container logs, config validation, agent tmux sessions, dashboard auth, and GitHub credential checks.
  • Cross-cluster migration — the manual procedure for moving a hive between clusters.
  • v2 → v4 migration — upgrading a v2 deployment: the config is compatible unmodified, and what actually changes is the image tag, the published 7681 port, and the Compose/Kubernetes security settings.
  • Dashboard route and health checks — dashboard-route-rbac.yaml, route_exists, listener probes, and alert behavior.
  • Agent self-healing watchdog — liveness and readiness reconciliation for launched agents: liveness classification, restart backoff, crash-loop escalation, the auth probe that refuses to restart into dead credentials, and the conditions array on /api/agents. Ships in mode: observe, which audits the restarts it would have made without making them.
  • Audit log format — the JSONL schema of /data/audit.jsonl: the five fields, how to parse the flat detail string (and why repo is not first-class), the pseudo-users, and why size-triggered rotation means the effective lookback varies per hive rather than being 90 days.
  • Delegation chains — the cryptographically verifiable record of which authorizations composed to produce an action: the RFC 8693-shaped act nesting, the five identity situations and their chain shapes, why a root is never fabricated, how a tenant verifies independently against the anonymously-published Ed25519 keys with no hive credentials, and the rotation story. Observe-only — chains are minted and published but gate nothing, and enforcement is a separate future decision.
  • hive-open-pr — how agents open pull requests as the App bot instead of via gh pr create: the flags, the UID-ownership anchor that makes the request forge-resistant, and the asynchronous contract (exit 0 means requested, not opened).
  • hive-merge — how agents merge pull requests as the App bot instead of the GitHub MCP merge_pull_request tool: the flags, the F4 target-binding (pinned head SHA + governor merge-eligible list), and the retry/re-engagement behavior when required checks are still red.
  • hive-open-issue — how agents create issues, post comments, and claim issues as the App bot instead of gh issue create/gh issue comment: the three request shapes, exact-title dedupe, and the exponential-backoff retry contract.
  • Network and port requirements — inbound ports, proxy paths, egress, and firewall guidance.
  • TLS, HTTPS, and certificates — termination patterns and certificate ownership.
  • Security notes — log scrubbing and secret redaction guarantees/limits.
  • Token collection and usage tracking — session JSONL, /api/cost, and hub usage rollups.
  • Notifications — ntfy, Slack, and Discord alert channels, plus the two-way Discord bot.
  • State-triggered hooks — declarative transition → action rules, the transition catalog, the vetted action set, and the security model (RFC #4001).
  • CEL-based agent triggers — the triggers: config key: declarative CEL rules that kick an agent on a normalized source-control event, additive to built-in label/governor triggering, the event.* field reference, and the fail-closed compile/runtime contract.
  • Public snapshots — read-only /snapshot, custom CSS, and frame-ancestor sharing.
  • hivectl — command-line client for the dashboard API.
  • bd beads CLI — work-ledger and knowledge command reference for operators and contributors.
  • Backup and restore — hive-backup, Kubernetes CronJob, spoke backup scope, and setting the backup encryption key from Governor Config (hosted flow). Host-level backup, restore, and docker compose down -v are given per runtime: Docker Compose, and Podman/Quadlet with the executed backup → wipe → restore cycle in both root modes, the rootless mapped-UID trap that makes a host-shell tar skip the GitHub App key, and the Docker→Podman migration (the two volume stores are never shared).
  • Hub disaster recovery — the hub-level runbook that goes beyond per-hive backup: hub backup and key escrow, spoke fleet recovery, Slack blast, and the full rebuild-from-zero procedure after a catastrophic loss.
  • Deployment helper scripts — the all-in-one LXC setup, Proxmox LXC, and blue-green Compose helpers. All are Docker-only; the page states each script’s runtime scope and where a Podman operator should go instead.
  • bin/ pipeline script index — map of the 45 deterministic pipeline and operational shell/Python scripts, grouped by function.
  • Dashboard API reference — pragmatic route index for dashboard and hub endpoints.
  • Dashboard OpenAPI spec — machine-readable REST API reference for integrations.
  • ioscan status — the untrusted-input scanner/canary feature (live and default-on in v4).
  • Deployment scripts — inventory of deployment helpers, including dashboard TTY panes and hive-panes.

Contributors and access

Configuration and agents

  • Agent configuration — agent fields, methods, models, pins, cadences, caveman mode, ACMM packs, and live-linked definition_source (with its seed-only trust model).
  • Advisory digest — what the digest shows (max_findings, show_all) and how findings are retired (staleness auto-close, PR-linked auto-close).
  • Advisory digest staleness — when the hub raises the stale-advisory pill and alert, the gates that deliberately suppress it (undelivered App, App cannot write, all agents quiet), and the admin diagnostics that measure hidden staleness.
  • Governor mode thresholds — how idle/quiet/busy/surge thresholds scale with repo count, the threshold_scaling curves, and when explicit thresholds win.
  • Supervisor agent — supervisor policy modes, bead roles, and when to enable the orchestration lane.
  • Telemetry agent — the L5/L6-only opt-in observability agent, ACMM level gating, and the project_observability opt-in flow.
  • Operations agent — the L5/L6-only opt-in operational-readiness agent (health checks, SLOs, runbooks), ACMM level gating, and the project_observability opt-in flow.
  • Custom dashboard stylesheets — operator-supplied CSS for the dashboard and public snapshot.
  • Portable AgentDefinition format — standalone YAML schema for importing/exporting agent definitions.
  • Knowledge curator — automatic fact extraction and promotion knobs, plus knowledge.git_sources: indexing a remote repo, layer semantics, private-repo auth (unsupported), and diagnosing a failed source.
  • Skill registry — the /data/skills/ file format and front-matter fields. Loaded and counted on the dashboard, but not yet delivered to agents: populating it changes no agent’s behaviour today. Use the knowledge curator for knowledge that actually reaches agents.
  • AGENTS.md repo instructions — the per-repo AGENTS.md file format Hive’s parser (pkg/agentsmd) understands, including front-matter skills: and inline ## Skill: sections. Wired into kicks, but needs a checkout: Hive agents keep no clones, so set project.checkouts_dir to a directory holding checkout per repo. Without it there is no root to read and injection stays a no-op, which is the default.
  • Agent peer-awareness logging (pluk) — pluk log format, hive-panes, availability, and retention.
  • Strategy Lab (Nous) — experiment lifecycle, dashboard/API configuration, fast-fail bounds, and the gate-decision flow. No nous: block in hive.yaml.
  • GitHub App setup — the Forge App on GitHub and GitHub Enterprise: app creation, permissions, Setup URL, and /gh-setup.
  • Forge setup: GitLab, Gitea, and Forgejo — the non-GitHub forges. Adapters exist and are tested, but are not wired into any running code path: a hive cannot run against GitLab, Gitea, or Forgejo today, and project.forge changes what the dashboard displays. Covers the gitlab:/gitea: config surface that does parse, why the gh-CLI agent path is GitHub-only, and how project.forge differs from github.forge.
  • ACMM policy matrix — capability levels and policy modes.
  • ACMM level-up advisor — the advisory-only pkg/acmmadvisor computation behind GET /api/acmm-recommendation: the signals it measures, per-level thresholds, and why it never changes the applied level.
  • Inception — operator guide to the L1 brainstorm/inception workflow: phases, API, and template variables.
  • Planning intelligence — how a large GitHub issue becomes an epic the architect lane decomposes into child beads, the human plan-review gate that withholds those children until approved, and stall-replan.
  • Review swarm — the five review perspectives, the verdict collector and its report contract, and the opt-in merge-gate integration and bounded auto-fix cycle for review findings.
  • Retro lane — the opt-in (retro.enabled) post-completion pass that reconstructs a record for each closed bead and flags patterns such as excessive fix attempts or kicks; deterministic by default, with LLM analysis separately opt-in.
  • Work sources — governor.work_source: the four type options (github default, github_projects, linear, jira), config fields, required credentials, and priority/hold-label mapping per source.
  • Linear agent integration — joining a Linear workspace as a first-class agent member: webhook verification, the 10-second session acknowledgement, which hive agent takes sessions, and narrating completion back as agent activities.
  • Lite enrollment — the zero-repo-secret on-ramp: hivectl enroll OWNER/REPO adds a repo to a spoke’s project.repos, with prerequisites and the hosted lite-spoke path.
  • ACMM policy fragments — per-level ACMM policy references.
  • Sandbox isolation and agent guardrails — isolation layers and operator guardrail notes.
  • Per-agent gh restrictions — file-based wrapper denials in /etc/hive/restrictions/.
  • Podman rootless CI — rootless Podman contract for contribute-hive.
  • Podman Quadlet .kube compatibility spike — why the standalone Kubernetes overlay is not a safe direct source for Podman units.
  • Podman ownership and cleanup contract — the labels that mark a resource Hive-owned and the guard that keeps Podman/Buildah cleanup from reaching the operator’s other containers, Distroboxes, and images.
  • Podman preflight: SELinux, mounts, secrets, and ports — read-only diagnostics for SELinux state and mount labeling, configuration/secrets readability, and published host-port availability, with remediation that never disables SELinux or widens a secret.
  • Podman preflight: subordinate IDs, graphroot, and networking — read-only diagnostics for rootless subordinate UID/GID delegation, unsupported (NFS and other distributed) container storage, and the rootless network backend/helper, with remediation that never edits /etc/subuid or /etc/subgid.
  • CLI backend setup — setup notes for Claude, Copilot, Goose, Bob, Pi, Codex, and Aider.
  • Inference backends — vLLM, llm-d, LiteLLM, and Model Gateway troubleshooting.
  • apiproxy — Anthropic-compatible proxy logging and deployment notes.
  • Outreach anti-spam ruleset — the deduplication and anti-spam rules the outreach agent operates under across awesome lists, project issues, directories, and community threads.
  • v1 to v2 migration — historical. Both ends of this migration are retired; v2 was retired in August 2026. Kept for operators still on v1, who should read it alongside v2 → v4 migration above. New deployments do not need it.

Architecture and design

  • Architecture — process model, governor loop, guardrails, hub/spoke, and walkthrough.
  • Hive federation design — the multi-hive registry: live /api/hives endpoints, project, contributor flow across hubs, and what remains future design work.
  • Public roadmap — the v4 direction as Now / Next / Later, with the tracking issue behind each item. Directional rather than a promise, maintained by pull request; check the date in its header before relying on the ordering.
  • Landscape and positioning — how Hive’s operations-plane design compares to nearby agentic orchestration tools, with public references per project. Explicitly time-sensitive; check the conducted date in its header before quoting product details.
  • CNCF reference architecture — CNCF submission/reference template.
  • Podman CI runner map — measured hosted-runner capabilities and which Podman lane goes where; SELinux is the lane needing non-hosted infrastructure.
  • Design documents — longer-form design records with the full reasoning behind a decision, indexed with a status each (shipped / partly shipped / design / historical) so a proposal is not mistaken for current behaviour: master secret rotation, wrapped master delivery to pull-only spokes, PR reach telemetry, and the knowledge system.
  • Podman Compose-provider selection spike — why podman compose must name its provider explicitly, and which provider needs no Docker tooling.
  • Trajectory review — trajectory safety lane and review signals.
  • Podman Quadlet .container/.pod spike — feasibility result for explicit Quadlet units: readiness via Notify=healthy, the startup-timeout trap, and what the generator does not validate.

Historical/design notes

Some documents describe planned or design-only work rather than live features. Those pages are marked at the top, for example Credly badges. The longer-form design records under design/ are a whole directory of these: each entry in that index carries a status, because those pages are the reference record of a decision and are deliberately not rewritten as later stages ship.

Security (v4)

  • Security model — operator guide — Ed25519-only sessions/SSO, per-hive keys, master key rotation, forced proxy egress and CAP_NET_ADMIN, privilege model, and supply-chain posture.

  • Security threat model — actors, boundaries, layered defenses, known gaps, and reporting.

  • Security response process — who responds to a vulnerability report (the Maintainer Committee, rostered in OWNERS), the end-to-end handling flow and the 60-day fix commitment, how membership is added and rotated, the escalation path if a reporter gets no response, and the project’s known limits stated plainly.

  • CNCF TAG-Security self-assessment — the CNCF Incubation self-assessment artifact: metadata, actors/actions/goals, critical security components with file/line citations, project compliance, secure development practices, vulnerability response process, and the three most significant known weaknesses stated plainly.

  • CNCF General Technical Review — the full Day 0/1/2 GTR questionnaire answered against this repository, cited file-by-file, with every currently-unanswerable question marked [NEEDS OPERATOR INPUT] rather than guessed at.

  • Heartbeat bearer cutover — retiring the fleet-wide heartbeat bearer, whose possession proves “some provisioned spoke” and lets any spoke heartbeat as any hive, in favour of the per-hive key — without re-provisioning the fleet, and the precondition that gates the removal.

  • Rootless Podman startup and exit-77 behavior — measured rootless matrix: fail-closed exit 77, gate installation under --cap-add NET_ADMIN, proven interception, and what is still unproven.

  • IPv6 egress-gate bypass — measured: the forced-proxy redirect is IPv4-only, so agent traffic to :443 over IPv6 never meets it (5 IPv6 connections, 0 redirects; 5 IPv4 connections, 5 redirects, same run). Names the fix slice.

  • Rootful Podman egress-gate baseline — the rootful baseline the rootless result is measured against: fail-closed exit 77, redirect and ambient-capability evidence, and SO_MARK isolated from the owner-UID exemption.

  • Podman support matrix: rootful/rootless × enforcing/advisory — the support statement for standalone Hive under Podman: which of the four combinations is supported, experimental, or a deliberate unenforced choice, what evidence settles each, and the gaps carried forward.

  • Release qualification: SELinux-enforcing Podman — the Podman lane hosted CI cannot run, and why: a per-release, reproducible procedure on an enforcing Fedora/CentOS Stream-class host covering :z/:Z mounts, MCS label behaviour, and secret access, with a results ledger and a stop condition that records UNEXECUTED rather than passing from a permissive host.

  • hive-data under SELinux enforcing — what the named volume actually guarantees: podman labels it container_file_t:s0 with no MCS category at create time, which is what lets a recreated container (a fresh category every start, --rm deleting the old) still read the data. Ownership after the copy-up, what survives unit deletion and reinstall, what does destroy it, why :Z on the volume line is a silent footgun where :Z on the config and secret bind mounts is correct, and why EnvironmentFile= needs no flag at all.

  • SELinux AVC evidence, and the hive-launch group secret — the audit-log evidence behind the qualification above: the actual AVC records per case rather than pass/fail inferred from an exit status, plus the 0440 hive-launch (GID 1002) secret read through a supplementary group. Records three defects in shipped advice, including a label check that reads garbage where uutils coreutils shadows GNU, and an MCS denial that produces no audit record at all.

  • Standalone Hive under Podman: the Quadlet units — the .container, .volume, and .network units that start Hive and its authenticating gateway on Podman in both root modes, the published-port boundary they encode (3001 published, the raw ttyd terminal on 7681 never) and how it was measured, the install and boot-persistence steps, and why systemctl start returning means the healthcheck passed rather than merely that a process was spawned. Also records the Docker-free run (#4448): the quick start executed verbatim with docker removed from PATH and DOCKER_HOST pointed at a nonexistent socket, reaching {"status":"ok"} on 3001 with no Docker socket mounted anywhere — and states plainly which #4188 criterion that closes and which stays open.

  • Quadlet lifecycle: stop, start, restart, recreate, and boot persistence — what those units actually report as an operator drives them, in both root modes, including the first live rootful start. Records that a clean systemctl stop left the unit failed, that systemctl enable fails outright on a generated unit, and that is-enabled cannot tell you whether Hive will come back after a reboot; ships bin/hive-podman-lifecycle-probe.sh as the repeatable check and records the reboot row as NOT EXECUTED rather than inferring it.

  • Host-execution capability matrix — what real execution environment can actually do, measured rather than asserted, before any new execution runtime is proposed on the strength of what it supposedly cannot. Command, exit status and verbatim output per capability for /dev/kvm, systemd, reboot, lingering, SELinux, rootful Podman, modprobe and NET_ADMIN. The result was not the expected: most are present, and the reason the reboot rows in the lifecycle page stay unexecuted is topology — the session runs on the host that would restart — not permission. Scoped hard to path on host, and says so.

  • Quadlet update and rollback: moving the image, and getting back — the deliberate manual path from Hive image to another and back, pinned by digest in a Quadlet drop-in because the shipped unit names a floating tag that cannot be rolled back to. Executed in both root modes between two real v4 builds: an 11-second healthy update, a failed update that held the unit in activating for the full 301-second TimeoutStartSec and then looped without ever reading failed, and an 11-second rollback out of it with hive-data intact throughout. Ships bin/hive-podman-update.sh.

  • Health-aware auto-update: whether it works on this unit, and what it costs — the #4411 decision, measured rather than assumed. podman auto-update --rollback DOES fire on this unit despite it never reading failed, because podman reads the D-Bus start-job result (timeout) and not ActiveState; Restart=always is kept untouched and never even fires. Driven against a bad-but-startable image. Also what it costs: full TimeoutStartSec of downtime per bad update, repeated on every timer firing because podman does not remember a rollback, and a digest pin that silently wins. Opt-in, via bin/hive-podman-update.sh autoupdate on. Executed in both root modes — rootless (#4411) and rootful under the system manager (#4447), which is the enforcing mode.

  • Architecture Decision Records — lightweight ADR process and records 0001-0017.

  • Intent verification — tier-based change authorization for merge eligibility.

  • Rootless Podman CI seam — documented test intent and static contract for contributor-container runtime handling.

  • Release-line carry-forward guard — the nine workflows pinned to hardcoded version-branch names, the single source of truth they are asserted against, and what to edit when a new release line is cut.