Hive

AI agent orchestration for open source projects. A single Go binary enumerates GitHub issues and PRs, classifies them by complexity, and dispatches work to AI agents (Claude, Copilot, Gemini, Goose) on adaptive cadences governed by queue depth.

Hive separates decisions into two layers: a deterministic pipeline of shell scripts handles filtering, classification, merge-gating, and enforcement before any LLM sees the work. Agents only handle judgment calls — reading code, reasoning about fixes, writing PRs.

Quick Start (Docker Compose)

git clone -b v2 https://github.com/kubestellar/hive.git
cd hive/v2

cp hive.yaml.example hive.yaml
export HIVE_GITHUB_TOKEN=ghp_...
docker compose up -d

Dashboard at http://localhost:3001.

To build from source instead of pulling the pre-built image:

docker compose build
docker compose up -d

Kubernetes Deployment

Prerequisites

• kubectl configured for your cluster
• Kubernetes 1.24+
• A StorageClass that supports ReadWriteMany (NFS recommended for zero-downtime rollouts)
• cert-manager (for TLS certificates)
• nginx-ingress (for ingress routing)

Hosted Option

The Hive Hub provides hosted hives with OAuth-protected dashboards, a public registry, and cross-hive leaderboards. No cluster required.

Self-Hosted Deployment

1. Create the namespace

kubectl apply -f deploy/k8s/namespace.yaml

Or manually:

kubectl create namespace hive

2. Create secrets

kubectl -n hive create secret generic hive-secrets \
  --from-literal=HIVE_GITHUB_TOKEN=ghp_... \
  --from-literal=HIVE_DASHBOARD_TOKEN=your-dashboard-auth-token

For GitHub App auth (recommended for production), add the private key:

kubectl -n hive create secret generic hive-secrets \
  --from-literal=HIVE_GITHUB_TOKEN=ghp_... \
  --from-file=gh-app-key.pem=/path/to/key.pem

3. Create ConfigMap from hive.yaml

cp hive.yaml.example hive.yaml
# Edit hive.yaml: set your org, repos, agents, and governor config

kubectl create configmap hive-config -n hive --from-file=hive.yaml=hive.yaml

4. Create PersistentVolumeClaim

Apply the provided PVC manifest:

kubectl apply -f deploy/k8s/pvc.yaml

The default PVC requests 10Gi with ReadWriteOnce. For zero-downtime rollouts with rolling updates, use an NFS-backed StorageClass with ReadWriteMany:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: hive-data
  namespace: hive
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: nfs
  resources:
    requests:
      storage: 10Gi

5. Deploy

kubectl apply -f deploy/k8s/deployment.yaml
kubectl apply -f deploy/k8s/service.yaml

The deployment runs a single replica with liveness and readiness probes on /api/health. Resource defaults: 500m CPU / 512Mi memory (requests), 2 CPU / 2Gi memory (limits).

6. Set up Ingress with TLS

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hive
  namespace: hive
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - hive.example.com
      secretName: hive-tls
  rules:
    - host: hive.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: hive
                port:
                  name: dashboard

Long timeouts are needed for SSE streaming connections to the dashboard.

Quick apply (all manifests)

kubectl apply -f deploy/k8s/namespace.yaml
kubectl -n hive create secret generic hive-secrets \
  --from-literal=HIVE_GITHUB_TOKEN=ghp_...
kubectl create configmap hive-config -n hive --from-file=hive.yaml=hive.yaml
kubectl apply -f deploy/k8s/pvc.yaml
kubectl apply -f deploy/k8s/deployment.yaml
kubectl apply -f deploy/k8s/service.yaml

Ports

Port	Purpose
3001	Dashboard (supports auth token)
3002	Internal API
7681	ttyd web terminal

Volumes

Mount Path	Purpose
/etc/hive/hive.yaml	Configuration (read-only, from ConfigMap)
/data	Persistent state: metrics, beads, logs
/secrets	GitHub App key and other secrets (read-only)

Configuration

All config lives in a single hive.yaml. Environment variables are interpolated with ${VAR} syntax. See hive.yaml.example for the full reference.

project:
  org: your-org
  repos:
    - repo-one
    - repo-two
  primary_repo: repo-one
  ai_author: your-bot-user

agents:
  scanner:
    enabled: true
    backend: claude
    model: claude-sonnet-4-6
    beads_dir: /data/beads/scanner
    clear_on_kick: true

governor:
  eval_interval_s: 300
  modes:
    surge:
      threshold: 20
      scanner: 15m
      reviewer: pause
    busy:
      threshold: 10
      scanner: 15m
      reviewer: 1h
    quiet:
      threshold: 2
      scanner: 15m
      reviewer: 45m
    idle:
      threshold: 0
      scanner: 15m
      reviewer: 15m

hub:
  enabled: true
  url: https://hive.kubestellar.io
  contribute:
    enabled: true

GitHub Auth

Use a personal access token or a GitHub App:

github:
  token: ${HIVE_GITHUB_TOKEN}

github:
  app_id: 12345
  installation_id: 67890
  key_file: /secrets/gh-app-key.pem

ACMM Levels

Hive uses an AI-native Capability Maturity Model (ACMM) with six levels that control what agents are allowed to do:

Level	Name	Agents	What agents can do
L1	Assisted	2	Interactive advisor and project inception. Advisory beads only.
L2	Instructed	5	Observe and report findings as dashboard beads. No GitHub interaction.
L3	Measured	6	Quality agent opens issues and hold-gated PRs. Others remain advisory.
L4	Adaptive	7	All agents file issues. Quality, sec-check, and CI open hold-gated PRs.
L5	Semi-Automated	9	All agents open hold-gated PRs. Humans batch-review and approve.
L6	Fully Autonomous	10	Agents open PRs and auto-merge on green CI. No hold label required.

Each level defines per-agent policy modes: advisory (observe only), measured (file issues), holdgated (PRs with hold label), or full (auto-merge). See v2/docs/acmm-policy-matrix.md for the full matrix.

Architecture

Hive runs as a single container with three processes:

• Go binary (hive) — orchestrates agent tmux sessions, runs the governor eval loop, serves the dashboard API, manages health checks and token tracking
• Node.js proxy — reverse proxy for the dashboard frontend with SSE streaming
• ttyd — web terminal for remote access to agent tmux sessions

Agents run inside tmux sessions managed by the Go binary. The governor evaluates queue depth on a configurable interval and switches between four modes (SURGE, BUSY, QUIET, IDLE), each with per-agent cadences. A deterministic pipeline of shell scripts pre-processes all GitHub data before agents are kicked.

Contribute to a Hive

Community members can contribute compute to any hive:

brew install just gh
git clone -b v2 https://github.com/kubestellar/hive && cd hive
just contribute-setup claude
just contribute-hive

Supported CLIs: Claude Code, GitHub Copilot, Pi, Goose, Bob. Contributors start as newcomer (rate-limited) and auto-promote based on completed tasks. Your credentials never leave your machine.

See the Hive Hub contribute page for details.

Contributing

See the Hive Hub to browse registered hives, view leaderboards, and find hives accepting contributions.

To contribute to Hive itself, open issues and PRs on this repository.

---

Apache 2.0