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

Hive v2 documentation

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.
• 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.
• Environment variable reference — centralized list of runtime, deployment, hub, backup, and contributor environment variables.
• Troubleshooting — v2 container logs, config validation, agent tmux sessions, dashboard auth, and GitHub credential checks.
• Notifications — ntfy, Slack, and Discord webhook setup, trigger events, and test commands.
• 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.
• Custom stylesheets — public CSS theme injection for dashboard, leaderboard, and snapshot surfaces.
• 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 — v2 status of the untrusted-input scanner/canary feature.
• 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. ioscan is also documented as absent from v2 HEAD until code is reintroduced.

Security (v4)

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