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.
• Release channels — stable/candidate/edge moving image tags, switching a hive to a channel, and the stable (v4) version pill.
• 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.
• 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.
• 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.
• 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).
• Deployment helper scripts — Proxmox LXC and blue-green Compose helpers.
• 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 v2 deployment helpers, including dashboard TTY panes and hive-panes.

Contributors and access

• ClankeR contributor relay — local contributor setup, multi-hub subscriptions, and role requests.
• Contributor trust tiers and delegated agent roles — newcomer/contributor/trusted/merger/advisor semantics, Acting as, grants, and delegatable roles.
• Credly badges — planned integration design; currently a placeholder mapping.

Configuration and agents

• Agent configuration — agent fields, methods, models, pins, cadences, caveman mode, and ACMM packs.
• Advisory digest — what the digest shows (max_findings, show_all) and how findings are retired (staleness auto-close, PR-linked auto-close).
• 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.
• 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.
• 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.
• ACMM policy matrix — capability levels and policy modes.
• Inception — operator guide to the L1 brainstorm/inception workflow: phases, API, and template variables.
• 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.
• v1 to v2 migration — migration checklist and rollback notes.

Architecture and design

• Architecture — process model, governor loop, guardrails, hub/spoke, and walkthrough.
• 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.
• Knowledge system design — llm-wiki layers, subscriptions, and APIs.
• 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.

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.
• 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.
• 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.
• 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.