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.
• Config layering — how ConfigMap seed, PVC dashboard overlay, and runtime config interact.
• Operator reference — top-level config blocks, hive flags/env, and GitHub token scopes.
• Cross-cluster migration — moving a hive between clusters without losing state.
• 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.
• 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.
• 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.
• Knowledge curator — automatic fact extraction and promotion knobs.
• GitHub App setup — app creation, permissions, Setup URL, and /gh-setup.
• ACMM policy matrix — capability levels and policy modes.
• 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.