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 historically named v2/ directory — the doubled v2 in repo paths is the directory name, not a branch). The v2 branch was retired in August 2026.

Start with Architecture for the system overview, then use the topic guides below.

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.
• 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.
• 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, and spoke backup scope.
• 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.
• 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 — 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.
• 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.
• Knowledge system design — llm-wiki layers, subscriptions, and APIs.
• Trajectory review — trajectory safety lane and review signals.

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.
• Architecture Decision Records — lightweight ADR process and records 0001-0010.
• Intent verification — tier-based change authorization for merge eligibility.
• Rootless Podman CI seam — documented test intent and static contract for contributor-container runtime handling.