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

Agent Configuration

A hive agent is a long-running AI worker — a CLI session the hive keeps alive in tmux, kicks on a cadence with a work prompt, and watches for stalls, rate limits, and login expiry. An agent’s configuration is YAML entry under agents: in hive.yaml: it names the agent, picks the engine that powers it (a subscription CLI or a self-hosted inference endpoint), and declares how it behaves. Everything else — cadences, models, pins, ACMM level — layers on top.

Start with a name, a method, and a model. Add the rest when the agent needs it.

The smallest agent that works

agents:
  scanner:
    backend: copilot
    model: claude-sonnet-4-6

For the portable agent definition YAML format, see ../AGENT-DEFINITION.md. For a complete portable AgentDefinition that exercises advanced display, channel, tool, and connection fields, see ../examples/agents/customized-agent.yaml.

That is a complete, valid agent. Defaults fill in the rest at load time:

• enabled: true (unless you explicitly write enabled: false)
• clear_on_kick: true — the session context is cleared before each kick
• id and role default to the agent’s name (scanner)
• bead_role: worker, beads_dir: /data/beads/scanner
• Well-known names (scanner, ci-maintainer, architect, supervisor, sec-check, quality, guide, strategist, outreach) also get a default emoji, color, aliases, and lane keywords, so a bare scanner: entry already shows up in the dashboard as 🔍 with sensible triage keywords.

You almost never write a full roster by hand: applying an ACMM level (below) generates for you, and the dashboard edits it live.

Where configuration lives

Hive’s config is layered, and the layering is the point: a file’s location says who owns the setting.

/etc/hive/hive.yaml            ← ConfigMap seed (Kubernetes) or bind mount (Docker/LXC).
│                                 The operator/platform layer. Re-seeded on every pod
│                                 boot; authoritative for acmm_level and hub.is_public.
├── /data/hive.yaml.dashboard  ← Dashboard overlay on the PVC. Every save from the
│                                 dashboard UI lands here, secret-free, and is merged
│                                 over the ConfigMap seed at the next boot. Wins for
│                                 everything except the two ConfigMap-owned keys.
├── /data/agent-configs/       ← <name>.yaml per dashboard-managed agent
│                                 (created, imported, or generated by an ACMM pack).
│                                 Merged over the agents: map at load time.
├── /data/hive.yaml.runtime    ← Persisted runtime config (was hive.yaml.bak). Never
│                                 edit. On K8s a post-merge snapshot the entrypoint
│                                 restores from if the seed is lost; on Docker/LXC the
│                                 boot-time source of truth. The legacy name is still
│                                 read as a fallback during the migration.
├── /data/secrets/             ← Secret VALUES written by the dashboard (writable PVC).
│   /secrets/                  ← Secret VALUES from Kubernetes Secret mounts (read-only).
└── /data/policies/agents/     ← Kick templates and per-agent policy Markdown.

Read the tree top to bottom and you can answer “who set this?” for any value:

• The platform owns the seed. In Kubernetes, an init container re-copies the ConfigMap to /etc/hive/hive.yaml on every boot. The entrypoint then merges the dashboard overlay over it — but the ConfigMap stays authoritative for the hub/admin-managed keys (acmm_level, hub.is_public).
• You (via the dashboard) own the overlay. Every dashboard save writes /data/hive.yaml.dashboard, so a LiteLLM endpoint or agent tweak survives pod restarts and upgrades.
• Secrets never enter YAML. hive.yaml stores env var names (api_key_env) and key file paths (api_key_file, governor.backup.key_file) — never key values. Values live in /data/secrets/ (dashboard-entered) or /secrets/ (Kubernetes Secret mounts). Because Config.Save() writes the whole config back to disk, a key value in YAML would be persisted in plaintext — so the code refuses the pattern entirely.

Anatomy of an agent

Every field below exists in the config schema today. Grouped by what it does:

Identity — how the agent appears

agents:
  scanner:
    display_name: scanner        # dashboard label (defaults to the YAML key)
    description: "Triages issues and opens hold-gated fix PRs."
    emoji: "🔍"                  # dashboard badge
    color: "#3498db"             # dashboard accent color
    role: scanner                # behavioral role; defaults to the agent name
    sort_order: 20               # dashboard ordering (supervisors default to 0, others 100)
    aliases: [sc]                # short names accepted in dispatch/commands

Engine — what powers it

    backend: copilot             # the method: claude | copilot | goose | codex | pi |
                                 #   bob | aider, or an inference backend:
                                 #   vllm | llm-d | litellm | watsonx | named gateway
    model: claude-sonnet-4-6     # model id for that method
    cli_pinned: true             # pin the CLI so nothing auto-switches it
    launch_cmd: "/usr/bin/copilot --allow-all --model claude-sonnet-4-6"
                                 # explicit launch command (optional — hive builds
                                 # from backend + model + mode when omitted)

The dashboard also offers gemini as a live method (with live model discovery); as a persisted backend: value in hive.yaml, stick to the validated list above.

Behavior — what it may do, and when

    enabled: true                # default true; set false to keep it configured but off
    mode: ISSUES_AND_PRS         # GitHub interaction tier: ADVISORY | ISSUES_ONLY |
                                 #   ISSUES_AND_PRS | ISSUES_PRS_MERGE
    bead_role: worker            # worker | supervisor (supervisors sort first,
                                 #   monitor the others); default worker
    kick_template: scanner-holdgated.md
                                 # named work-prompt template in the policies dir
    include_repos: true          # append the project repo list to each kick (default true): false             # true = never kicked by the governor timer;
                                 # triggered explicitly (e.g. inception)
    clear_on_kick: true          # default true; false keeps session context across kicks
    stale_timeout: 28800         # seconds of silence before the agent counts as stale —
                                 #   must exceed its longest cadence
    restart_strategy: immediate  # how to bring a dead session back
    beads_dir: /data/beads/scanner   # work-record (bead) storage; default per-agent
    replicas: 3                  # materialize scanner, scanner-2, scanner-3 (max 5)
    lane_keywords: [bug, triage, fix]   # routes matching issues into this agent's lane
    detect_keywords: [scanner, triage]  # attributes GitHub activity back to this agent

For prompt file resolution and the complete built-in ${VAR} reference, see Policy and prompt templates.

Declarative extensions

Three optional blocks replace hardcoded behavior with declarations:

    channels:                    # how the agent gets triggered. Omit = governor timer.
      - type: kick               # kick | webhook | discord | schedule | bead
      - type: webhook
        events: ["issues.opened", "issues.labeled"]
        repos: [repo-one]        # optional repo-name filter
      - type: bead
        match: { nudge_target: scanner }
      - type: schedule
        schedule: "0 */4 * * *"  # cron; required for type: schedule
    tools:                       # tool permissions. Omit = the mode field governs.
      preset: issues-only        # advisory | issues-only | issues-prs | full
      rules:                     # per-tool allow/deny overrides on top of the preset
        - pattern: "mcp__github__create_issue"
          action: allow
          reason: "advisory issues are fine"
    connections:                 # external integrations
      - name: github-mcp
        type: mcp                # mcp | api | knowledge
        uri: "stdio:///usr/local/bin/mcp-github"

Presets map modes (advisory denies issue and PR creation, issues-only denies PRs, issues-prs and full deny nothing), and an explicit allow rule overrides a preset deny.

Replicated agents

Set replicas: N on a declared agent to run a small pool with the same prompt, backend, model, mode, channel, tool, and metadata settings. N defaults to 1 and is capped at 5; config load fails if it is outside 1..5. Hive materializes derived names as -2, -3, … (scanner, scanner-2, scanner-3). Do not declare those derived names yourself: a real scanner-2 entry collides with scanner: { replicas: 2 } and is rejected. Derived replicas get their own IDs and bead directories (/data/beads/scanner-2) but inherit the base agent’s kick template/prompt selection. Runtime-derived replicas are stripped before saving and recreated on the next load.

Trigger channels

channels: declares non-default ways to wake an agent. If the block is omitted, governor timer kicks still work. If you include the block, add type: kick when the agent should keep normal governor kicks alongside other triggers.

Rounding out the schema — fields you will rarely touch:

Explain mode (debugging agent behaviour)

Agents are told to act, not narrate. Every policy carries an “Output Rules — Terse Mode” block, and on inference backends the agent manager appends an explicit EXECUTE, DO NOT NARRATE instruction to each kick. That rule earns its keep — weak models otherwise answer a kick with a plan for someone else to run instead of running it — but it also means that when an agent does the wrong thing, there is nothing in the log saying why.

explain_mode buys that visibility back for agent at a time, without relaxing the rule for anything else.

agents:
  scanner:
    backend: claude
    explain_mode: brief

What it does and does not change

• The agent still acts. The instruction states that tool execution remains the requirement and that a response containing explanation is a failure. It is appended after the EXECUTE, DO NOT NARRATE block, so it reads as a qualification of that rule rather than a replacement for it.
• Terse mode is suspended on EXPLAIN: lines. A caveman-compressed explanation would be useless to the human reading it, but the agent’s real output — log lines, bead titles, PR descriptions — keeps whatever compression you configured.
• It is per-kick, not a prompt edit. Nothing in v2/policies/ or examples/*/agents/*.md changes, so toggling it does not alter any agent’s actual instructions and does not require a redeploy.

Reading the explanation

Explanation lands in the agent’s ordinary log, tagged with the EXPLAIN: prefix. Agent logs are tmux pane scrapes, so there is no second channel to write to — but the prefix makes the split a read-time choice:

grep EXPLAIN: works the same way on a downloaded log.

Fleet-wide default

Set HIVE_EXPLAIN_MODE on the hive to turn explanation on everywhere without editing each agent:

HIVE_EXPLAIN_MODE=brief

The per-agent field is a tri-state, and the difference matters:

An unrecognized value in either place resolves to off, so a typo degrades to the previous behaviour rather than to a mode nobody asked for. Hive injects the resolved mode into each agent process as HIVE_EXPLAIN_MODE, so an agent’s own skills and scripts can branch on it without re-deriving the precedence rules.

Leave it off outside of debugging: the explanation is extra output tokens on every kick.

Caveman prompt compression

caveman_mode installs the upstream JuliusBrussee/caveman skill/proxy for supported backends before an agent starts. It is optional and experimental; leave it empty for maximum output fidelity.

Implementation notes from v2 HEAD:

• Config validation accepts lite, full, ultra, wenyan, or empty.
• claude, copilot, and gemini are auto-wired before first message.
• goose, codex, and aider get the skill installed and then receive /caveman <mode> after the CLI reaches an input prompt.
• Unsupported backends log that caveman is not supported and continue without compression.
• The UI describes the feature as roughly 65% output reduction, but exact savings vary by prompt, backend, and task.

Methods: subscription CLIs vs self-hosted inference

backend: picks of two families. They differ in how you authenticate and where model lists come from:

Two rules of thumb:

• CLI methods are subscriptions. You log in per method from the dashboard, and every agent using that method shares the login.
• Inference methods are endpoints. You configure a base URL and a key reference (env var name or key-file path — the value goes in /data/secrets/, never in YAML). Agents on vllm/llm-d/litellm launch the Claude CLI routed through hive’s inference translator, so there is no separate login.

Every Model Gateway (and the bob backend) also accepts an optional key_name — a human-chosen LABEL for the configured key, e.g. key_name: openrouter-prod-key. It is safe-to-show metadata, not a secret: the dashboard’s gateway row displays it as “Using key: <name>”, or “(unnamed)” when no label is set, so operators can tell keys apart without ever seeing the value. See inference-backends.md for a full YAML example.

Kubernetes manifests for deploying inference backends (vllm Deployment, EPP RBAC, kustomization) are in deploy/inference/.

Agents can inspect peer panes with hive-panes [lines] when the deployment includes src/deploy/hive-panes.sh. It reads pluk JSONL logs from /var/run/pluk/logs, skips the calling agent named by HIVE_PROXY_AGENT, strips terminal escapes, and prints the last N raw-output lines for every other agent. Use it for situational awareness; it is read-only and does not attach to another agent’s tmux session. See Agent peer-awareness logging for the pluk log format, when it’s available, and its retention behavior.

Every discovery probe is best-effort: a failed or absent probe falls back to a current static list, so a model dropdown is never empty. Fallback entries are marked “unverified” in the UI.

Model pinning and auto-switching

Each agent shows a 📌 pin on its CLI and its model in the dashboard. The semantics are deliberately narrow — a model changes out from under you in exactly two cases:

1. Unpinned + governor. The governor may auto-select a different model (budget, mode). A pin blocks this — and only this. Your own explicit switch always goes through; it simply retargets the pin to the new model, so the agent stays pinned.
2. Discovery says the model is gone. When a genuine (non-fallback) discovery returns a model set that no longer contains an agent’s selected model — a key swap or endpoint change stripped the entitlement — the agent is switched to the first available model, with a toast. A static-fallback list never triggers this, and a model that is still present is never re-selected.

Pin a model when reproducibility matters more than the governor’s budget optimizations. Leave it unpinned when you want the hive to manage cost for you.

Cadences and the governor

Agents don’t schedule themselves. The governor evaluates the work queue every eval_interval_s (default 300s), computes a mode from queue depth — idle → quiet → busy → surge (default thresholds: quiet > 2, busy > 10, surge > 20 per watched repo; override with threshold:) — and kicks each agent on the cadence that mode assigns it:

governor:
  eval_interval_s: 300
  modes:
    busy:
      threshold: 16        # queue depth that activates this mode
      supervisor: 5m       # per-agent kick interval in this mode
      scanner: 15m
      reviewer:
        times: ["09:00", "17:00"]
        days: ["mon", "tue", "wed", "thu", "fri"]
        tz: America/New_York
      release:
        cron: "30 9 * * 1-5"
        tz: America/New_York
      ci-maintainer: 1h
      architect: pause     # "pause" stops kicks for this agent in this mode

• Thresholds scale with repo count. The default thresholds above are per-repo bases, multiplied by len(project.repos) — so surge is 20 on a 1-repo hive and 780 on a 39-repo, and the mode ladder means the same thing at any hive size. A threshold: you set yourself is used verbatim and never scaled. Tune the curve with governor.threshold_scaling (linear default, sqrt, none). See Governor mode thresholds, which also covers the ACMM-pack interaction.
• Mutually exclusive modes. Each per-agent, per-mode cadence is either an interval (5m, 2h, pause) or a time-of-day schedule — never both. Config load and API writes reject mixed forms with a 400/error.
• Time-of-day schedules. Use times: ["HH:MM"] with optional days (mon … sun) and a required IANA tz. The timezone is stored explicitly and displayed with the schedule; it does not float with the viewer.
• Advanced cron. Power users can provide a constrained five-field cron expression plus tz. Hive evaluates these with robfig/cron and schedule-local timezone handling.
• Governor-mode semantics. Time-of-day schedules fire at their exact wall-clock times. Governor mode selects whether that mode’s schedule is active; quiet/busy/surge multipliers do not scale exact times. pause/off, paused agents, on-demand agents, non-kick channels, and budget gates still suppress kicks.
• Downtime catch-up. If Hive was down at a scheduled time, restart/eval grants at most catch-up kick when the missed occurrence is within the last 10 minutes. Older missed occurrences are skipped and the next future occurrence is used.
• Per-agent, per-mode intervals. Anything Go’s duration parser accepts works (5m, 2h) for interval mode.
• Pausing. The value pause (or paused) suspends an agent for that mode without disabling it.
• On-demand agents (on_demand: true) are skipped by the governor timer entirely — they run when explicitly triggered (the inception workflow drives brainstorm this way).
• Budget. When the weekly token budget is exhausted, kicks are suppressed hive-wide (exempt agents excepted) until the period rolls over.

Set stale_timeout with your cadences in mind: an agent kicked every 4h with a 30-minute stale timeout will look dead between kicks. The shipped packs use “longest cadence × 2”.

ACMM levels: agent rosters as packs

You don’t have to design a roster. Hive ships six ACMM packs (level-1.yaml … level-6.yaml, embedded in the binary and forkable) that pair a curated agent roster with governor cadences and a merge policy:

Applying a level reconciles the whole roster, not just the diff: missing agents are created (as overlay files in /data/agent-configs/), existing agents are merged — pack values fill blanks, but your explicit backend:, model:, and enabled: false always win — and the level’s kick_template and mode are updated so the agent’s policy matches the level. A failed agent doesn’t abort the rest; the level is recorded as cleanly applied when every agent reconciled.

The L5 roster is the canonical worked example — nine agents, eight on the governor timer plus on demand:

At L5, every agent PR gets a hold label automatically. The system proposes; it does not merge autonomously.

Kick templates: what an agent is told to do

kick_template names a Markdown file resolved from the hive’s policies checkout (/data/policies/examples/kubestellar/agents/, or the directory your policies: config points at), falling back to the defaults embedded in the binary (src/pkg/policies/defaults/). It is the agent’s periodic work prompt: on every kick, the template is loaded, variables like ${ISSUE_LIST}, ${PR_LIST}, ${AGENT_NAME}, ${PROJECT_ORG}, and ${KNOWLEDGE} are substituted, and the result is dispatched to the agent’s session.

Resolution order: the agent’s explicit kick_template wins; otherwise the ACMM pack’s template for that agent at the current level; otherwise convention — /data/agents/<name>/CLAUDE.md, then <name>.md in the policies checkout, then the embedded default. Pack templates carry the level’s policy in their names — scanner-holdgated.md is scanner-at-L5; the same scanner at L6 gets scanner-automerge.md.

Portable agents bundle everything — config plus a promptTemplate — in a single AgentDefinition YAML you can import from a URL in the dashboard. The reference schema is ../AGENT-DEFINITION.md, and a worked example lives at ../examples/agents/customized-agent.yaml.

Label policy: which issues agents may work

There is exactly one label-policy surface for the hive’s own agents — the Governor Configuration → Labels tab — and it has two polarities:

By default a hive treats every open issue in its repos as candidate work. Projects that gate automation on a maintainer’s explicit approval label want the require polarity: a maintainer reviews an issue, applies the approval/queue label, and then may agents touch it. (A fleet running against a busy upstream repo hit exactly this — the hive opened a PR for an issue the owner had not yet labeled for agent work; an exempt list cannot express that policy, because it can name what to avoid, not demand a label be present.)

project:
  org: my-org
  repos: [my-org/common]
  issue_filter:
    require_labels: [approved-for-agents]   # agents may work these issues

Semantics:

• Absent/empty require_labels = no gate — existing hives are unchanged; there is no default-on filtering.
• An issue must carry at least required label to be eligible. Matching is case-insensitive and exact (a prefix like approved-for-agents-maybe does not satisfy approved-for-agents — prefix matching would over-admit through an approval gate).
• Exempt wins on conflict: an issue carrying both an exempt label and a required label stays excluded. There is deliberately no separate exclude_labels field — the exempt list is the exclusion mechanism, applied first.
• PRs and the Hold list are unaffected: open PRs are in-flight work, and held issues still appear under On Hold.

Both polarities are enforced at enumeration — the point where GitHub issues become the hive’s actionable set — not in the prompt. A filtered issue never enters the queue, never appears in a kick, never triggers plan-from-label, and cannot be re-selected by a confused (or prompt-injected) agent re-listing the repo. Kick prompts additionally state the active require policy so agents know the list is intentionally short. Both lists are edited on the Labels tab; an active require gate is also noted read-only under Repositories, and hub-managed hives can receive issue_filter with their project config over the heartbeat.

Not the same thing as the contribute filters. hub.contribute_labels_mode + its label list gate which issues are handed out to external contributors over /contribute — they have never gated the hive’s own agents, so an operator who allow-listed a queue label there (a common setup for routing labeled issues to contributors) still had a hive whose own scanner could work every other open issue. project.issue_filter.require_labels is the agent-side gate; configure both if you want the same label to govern both lanes.

When to add what

What to read next

• Supervisor agent — what the supervisor does, how it differs from the governor, when to enable it, bead_role semantics, and policy modes.
• Documentation index — what hive is, setup, and the full topic-guide surface.
• Architecture — process model, deterministic pipeline, governor loop, guardrails, and hub/spoke design.
• Portable AgentDefinition format — standalone YAML schema for agent imports, exports, and overlays.
• Dashboard route and health checks — listener probes and alert behavior for stuck sessions and restart loops.
• Troubleshooting — stuck sessions, login expiry, restart loops, and notification checks.
• ACMM policy matrix — the full per-level, per-agent policy table.
• Config layering — precedence for seed, dashboard overlay, agent overlays, and runtime snapshots.
• Cross-cluster migration — the manual procedure for moving a hive (and its PVC state) between clusters.
• Dashboard OpenAPI spec — REST endpoints used by the dashboard and integrations.
• SQLite state backend example — single-machine alternative to beads for state queries.
• ACMM policy fragments — per-level ACMM policy reference fragments.