Last reviewed: 2026-10-23
Hive runs AI coding agents against real repositories. This page is the inventory of the controls that limit what an agent can do, with the file or setting behind each one. Hive's design rule is that anything a human would decide the same way every time belongs in infrastructure, not in a prompt: the controls below are Go, shell and kernel mechanisms, not instructions to a model. Where a control is a proposal rather than code, the page says so.
An inventory is not a promise that every running hive has every control on. Check the effective configuration before relying on a gate; a dashboard toggle alone is not evidence of enforcement.
Companion pages: security-threat-model.md (attacker view), security.md (log scrubbing), securing-your-hive.md (first-time operator guide).
- First-time operator: use the guide above for trust choices and who can merge. This page is a technical inventory, not a deployment checklist.
- Check a running hive: start with Human in the loop and the inventory's “How to check” column. Dashboard owners can inspect effective settings; file, kernel and network checks need deployment-admin access. Hosted owners should ask their hub operator for those checks.
- Audit the implementation: use the control sections and verification procedure. Do not change production state or print secrets to prove a check.
Terms used below: a UID is a Unix user ID. A cgroup tracks and limits a process group's resources. Egress means outgoing network traffic. MITM means man-in-the-middle: Hive's local inspecting proxy. A PAT is a personal access token. A JWT is a JSON Web Token; its TTL is its time to live. CSP is Content Security Policy, a browser restriction on page resources and scripts. These names describe mechanisms, not proof they are enabled on a given hive.
- Prompt injection. Issue and pull-request text, labels, comments, cloned repositories and tool output are attacker-controlled and reach the agent's prompt.
- Runaway or stuck agents. Loops, token burn, endless re-dispatch, wedged terminals.
- Credential theft. An agent printing, pushing or sending a GitHub token, provider key or hub secret off host, or reading another agent's.
- Bad merges. Code landing without CI, review or human sign-off, or at a different commit than the one judged.
- Over-trusted contributors. Humans or bots steering agents, claiming work above their trust, adding themselves as owners, or weakening CI.
- Cost abuse. Token burn, API rate-limit exhaustion, label and comment storms.
- Platform compromise. Unauthorized dashboard or terminal access, forged hub-to-spoke messages, cross-tenant exposure on the hosted hub.
- Supply chain. Poisoned base image, npm install script, unpinned Action or vulnerable Go dependency.
| Control | Mitigates | Where it lives | How to check it is on |
|---|---|---|---|
Fresh context per task (clear_on_kick) |
injection persistence | src/crux/agent/manager_kick.go |
hive.yaml agent block |
| Watchdog and crash-loop pause | stuck agents | src/crux/agent/watchdog_fleet.go |
conditions[] in GET /api/agents |
Per-agent Unix users, su-exec 4750 |
cross-agent access, privilege escalation | src/deploy/entrypoint.sh, src/Dockerfile |
/var/run/hive/uid-map.json; suid-contract CI job |
| Per-agent tool denials; GitHub MCP writes denied | GitHub writes through tools | src/crux/agent/manager_launch.go |
agent launch command |
| Credential-free sandbox and push broker (opt-in) | credential theft | src/crux/sandbox, src/crux/pushbroker |
agentSandboxEnabled in GET /api/config/governor |
| Work ledger and knowledge store instead of memory | injection persistence | src/pkg/beads, src/pkg/knowledge |
bd CLI |
ioscan scanning and canaries (default on) |
prompt injection, secret leakage | src/pkg/ioscan |
ioscanEnabled, ioscanFailMode in GET /api/config/governor |
| Trajectory review (default on) | goal drift | src/crux/trajectory |
governor.trajectory.enabled |
| Policy proxy and repo allowlist | credential theft, out-of-scope writes | src/crux/proxy/rules.go |
403 with X-Hive-Proxy-Blocked |
| Forced egress through the proxy (iptables) | proxy bypass | src/deploy/entrypoint.sh |
boot log; no HIVE_PROXY_ADVISORY_OK |
| Tiered GitHub tokens per agent mode | blast radius of a leaked token | src/crux/agentmode, src/crux/agent/manager_tokens.go |
token tier on the agent card |
| Proxy-side credential injection (opt-in) | token theft | HIVE_PROXY_INJECT_GH_AUTH |
security.credentialInjection in governor config |
| Inference-key placeholder swap | provider key theft | src/pkg/apiproxy |
agent env shows sk-hive-<agent> |
gh wrapper with per-agent restrictions |
denied commands | bin/gh-wrapper.sh |
gh resolves to /usr/local/bin/gh |
hive-open-pr / hive-merge relays |
forged authorship, stale-commit merges | bin/hive-merge.sh, bin/hive-open-pr.sh |
POST /pulls returns 403 for agents |
| Automerge gates | bad merges | src/pkg/github/automerge/automerge_sweep.go |
skip reasons in audit entries |
| Intent verification | scope creep, guardrail edits | src/pkg/intent |
intentEnforce in governor config |
| Hold guard | drift after approval | src/pkg/holdguard |
evidence comment on held PR |
| Escalation circuit breaker | fix loops | src/pkg/escalation |
needs-human label |
| Sentinel (eight rules) | malicious PRs, CI weakening | src/pkg/sentinel |
sentinel-alert label |
| Reporter trust (opt-in) | hostile issue reporters | src/pkg/config/reporter_trust.go |
reporter_trust.enabled |
Dashboard roles (read/read-write/merger/owner) |
unauthorized writes | src/pkg/dashboard/api_auth.go |
403 on write as read |
| Audit and token-access logs | unattributed actions | src/pkg/dashboard/audit.go, src/pkg/agentaudit |
GET /api/audit |
| Token budget and per-pass caps | cost abuse | src/pkg/governor/governor.go |
governor.budget.* |
| Pause switches | emergency stop | project.paused_repos, POST /api/pause/<agent> |
config |
| Webhook signature check | forged events | src/pkg/dashboard/api_github_webhook.go |
unsigned request rejected |
| Hub auth (Ed25519 sessions, per-hive bearers) | platform compromise | src/pkg/hub/saas_auth.go |
GET /api/saas/admin/auth-rollout |
| Content Security Policy and headers | dashboard XSS | src/pkg/dashboard/server.go |
response headers |
| Log scrubbing | secrets in logs | src/crux/logscrub |
redacted patterns in logs |
| Supply-chain guards | supply chain | .github/workflows/*.yml, src/Dockerfile |
PR checks |
| DCO on every commit | unattributed code | src/scripts/check-dco-trailers.sh |
DCO check on PR |
Bounded runs. Work arrives as discrete tasks from the governor. By default each task starts with a cleared model context, so the agent begins from the task text and its instructions file, not from what a previous issue author wrote. A resumed pull-request session is the deliberate exception. A turn ceiling bounds how long the governor waits on a continuous turn. The watchdog classifies every agent pane on each tick, restarts dead panes with backoff from one to sixteen minutes, and after five failed restarts pauses the agent and raises an alert until a human intervenes. Context reset is not process reset: the CLI process and its on-disk session state persist until restart.
Separation. Each agent runs as its own Unix user (from UID 2001), in its
own tmux server on its own socket, with its own home directory and token
file. Token files are owned by the agent's group with mode 0640 or by the
agent with mode 0600. Agents cannot attach to each other's sessions, signal
each other's processes or read each other's tokens. Agents coordinate through
the work ledger and GitHub, never by reading transcripts.
Tool denials. Per-agent tool rules in hive.yaml become hard CLI flags
at launch. GitHub MCP write tools are denied for every agent in every mode.
Claude Code's Remote Control feature is pinned off in every agent's settings
at each launch.
Privilege model. The hive process runs as user dev (UID 1001).
su-exec is the only setuid binary in the image, mode 4750 root:hive-launch,
so no agent user can run it. The setuid bits on the eleven setuid or setgid binaries the Debian
base image ships are stripped at build, and the build fails if the
inventory is anything but su-exec. allowPrivilegeEscalation: false is not used
because it would disable su-exec and break agent launch. The proxy CA
private key is stored with mode 0600 in a 0700 directory.
Credential-free sandbox (opt-in). A task can run in a rootless Podman
container or a Kubernetes Job that holds no credentials. Both the global
agent_sandbox.enabled and the per-agent sandbox.enabled must be set. A
push broker outside the sandbox scans committed diffs for secrets and
protected-path edits, mints a short-lived token and pushes the branch. See
sandbox-isolation.md.
Hive replaces long-lived agent memory with two inspectable stores. The work
ledger holds typed work items, status and notes as git-backed JSON. The
knowledge store holds typed facts with sources and confidence. Neither stores
conversation text. Agents are primed with a bounded set of facts in the task
prompt; they cannot query the store, so a poisoned fact cannot be amplified.
Untrusted text is scanned by ioscan before it reaches a prompt
(ioscan.md). Inbox item text (voice and meeting transcripts,
summaries, messages) is fenced in a nonce-tagged <untrusted-inbox-data>
envelope before it reaches spektacular or an agent prompt
(inbox-voice-sources.md); canaries are planted per task and agent output is
scanned for them. Session state is pruned and logs are scrubbed
(security.md).
Untrusted recordings transcribed by the built-in whisper provider are decoded
and transcribed outside the hive process, in the hive-whisper sandbox: a
separate hive-transcribe uid with no home, shell or supplementary groups,
reached through su-exec; an empty environment (no tokens or keys); the audio
on stdin and the model as an inherited read-only descriptor; a private 0700
work dir removed on exit; FFmpeg (an LGPL build with only audio demuxers and
decoders and no network protocols) and whisper.cpp under rlimits (address
space, CPU seconds, file size, open files, no core dumps), nice and a
wall-clock timeout scaled to the recording; and an empty network namespace
where the kernel allows unprivileged user namespaces. With whisper the audio
never leaves the spoke; with Gemini or Deepgram it is sent to that provider
under the hive's own account (inbox-transcription.md).
Files dropped onto the Inbox (owner and read-write only) are typed by content,
not by name or client MIME type: magic bytes refuse executables, archives,
PDFs, Office and media files whatever they are called, then the text must be
UTF-8 and parse as the format its extension asks for. Extraction runs with a
timeout and size caps; the original, the extracted text and the meta are
stored 0600 in a 0700 directory per upload, never executed or served raw, and
bounded by a per-hive quota. The extracted text is fenced in the same
<untrusted-inbox-data> envelope in its Knowledge fact and before any agent
prompt (inbox-uploads.md). Uploaded PDFs are never parsed in the hive process: the
hive-pdftext sandbox reads them as the hive-transcribe uid through
su-exec with an empty environment, under prlimit (address space, CPU, file
size, open files, no core dumps) and nice, in an empty network namespace
where the kernel allows it, from a private 0700 work dir, with a wall-clock
timeout that kills the process group. Word documents are read in
Go with zip-bomb caps (entry count, declared and actual inflated size,
compression ratio) and an XML decoder that refuses DTDs and unknown entities
(no XXE). Links dropped onto the Inbox are
fetched by the hive under an SSRF guard: http/https only, no credentials in
the URL, the hive's own DNS lookup with the connection pinned to the checked
address (any private, loopback, link-local, CGNAT, multicast, ULA or metadata
answer refuses the link), every redirect re-checked (at most 3), the body
size- and time-capped, and the environment proxy never used.
Inference keys. An agent using a self-hosted inference gateway is
launched with a placeholder key, sk-hive-<agent>, and a base URL pointing
at a translator proxy on loopback inside the pod. The translator recognises
the agent from the placeholder and attaches the real key server-side. The
real key is read from a key file, a Kubernetes Secret mount, or an owner-only
file on the volume, never from hive.yaml, which records only paths and
variable names. The dashboard never returns a key value. Agents using cloud
CLI backends (Claude, Copilot, Codex, Goose) run with the provider credential
you connected, because the CLI needs it.
Secrets at rest. The secret values a spoke stores on its data volume
(the owner-only key files under /data/secrets, the Copilot device-flow
token, and the github.token value in the persisted runtime config) are
sealed through a keystore provider interface
(#18214). Each value is
written as a single-line envelope, hive-enc:v1:<provider>:<key generation>:<ciphertext>, bound with additional authenticated data to the
slot it belongs in, so a ciphertext moved from one file to another does not
open. The default provider derives an AES-256-GCM key with HKDF-SHA256 from
HIVE_SECRETS_KEY (or a key file), falling back to the per-hive
HIVE_HEARTBEAT_KEY the hub already injects into the Deployment; a distinct
info string keeps the encryption key separate from the signing key it is
derived from. The threat this closes is the data volume on its own: a PVC
snapshot, a backup archive or a copied disk no longer yields the credentials.
It does not protect against an attacker who also holds the Deployment
environment or the hub master key. Files written before the keystore existed
are re-sealed on their first read, and a boot sweep converges the ones
nothing reads, so an existing hive needs no migration step; a retired key
generation is accepted for decryption through HIVE_SECRETS_KEY_PREVIOUS
while that happens. A hive with no key material keeps plaintext storage and
says so once at WARN; it never seals with a key stored beside the data.
OpenBao Transit is available as an opt-in provider
(#18216). Agent-facing
credential files and the read-only /secrets Kubernetes mount are not
touched. Variables: env-vars.md.
GitHub blast radius. The recommended authentication is a GitHub App, whose reach is limited to the repositories it is installed on. Hive mints a token per agent matching its mode: advisory agents get read-only tokens, measured agents can write issues, hold-gated and full agents can write code. The repo allowlist is enforced at the proxy and repeated in every task prompt. Below L6, no agent token can merge. Agent policy requires DCO sign-off; pair it with a DCO check on your repos for a hard gate.
The gh wrapper and relays. /usr/local/bin/gh is a wrapper that
applies per-agent restriction rules and injects the agent's token; agents
never pass tokens themselves. A scrub script runs at the start of every shell
in the agent's process tree and removes inherited credentials. POST /pulls
and PUT /pulls/{n}/merge are denied at the proxy for every mode; agents call
hive-open-pr, hive-open-issue, hive-merge and hive-review, which drop
a request file that Hive processes as the App. The merge relay requires the
expected head commit and checks the pull request is on the governor's
merge-eligible list at that commit.
Proxy-side credential injection (opt-in). With
HIVE_PROXY_INJECT_GH_AUTH=true, the agent's token file holds only a
placeholder and the proxy swaps in the real token on GitHub API requests. It
requires GitHub App authentication and is refused if advisory proxy mode is
also set, because advisory mode trusts a self-asserted agent name. A
default-on version with a signing sidecar was proposed in
#9586 and declined in
September 2026; injection stays opt-in. Rotation of contributor registration
tokens is a separate open item
(#13804).
Forced egress. The entrypoint installs an iptables rule redirecting all
outbound port-443 traffic through the proxy, so agents cannot bypass it with
a raw token. This needs CAP_NET_ADMIN; without it the spoke refuses to
start unless HIVE_PROXY_ADVISORY_OK=true is set, which makes the gate
advisory only. Rootless Podman cannot grant NET_ADMIN, so rootless
deployments are unsupported for enforcement. The proxy identifies the calling
agent by the user ID that owns the socket, read from /proc/net/tcp, which a
process cannot forge. Only api.github.com is inspected; other hosts are
tunnelled without inspection. See
net-admin-requirement.md.
Plain-HTTP forwards and uninspected tunnels. The redirect covers port 443
only, so plain HTTP reaches the proxy through its explicit proxy port. Those
forwards are identified like any other request and dialled only when the
resolved address is globally routable: loopback services beside the proxy, the
link-local metadata endpoint, RFC 1918/CGNAT cluster addresses and multicast
are refused with 403 and counted as violations (loopback excepted — agents
are handed NO_PROXY for it, so it is logged as the client misconfiguration it
is). The same policy applies to the tunnels the proxy does not inspect: a
CONNECT to a host other than the inspected API and the transparent-TLS
passthrough for such a host are dialled through the same guarded dialer, so
CONNECT 169.254.169.254:80 or an SNI naming a cluster address is refused on
the same terms rather than tunnelled from the proxy's own uid. The check runs
at dial time on the resolved address, so a hostname pointed inward is refused
on the same evidence as a literal IP. Set
HIVE_PROXY_ALLOW_PRIVATE_FORWARD=true only where a private-network
destination is intended; it lifts the guard for all three legs at once, and the
proxy warns at boot when it is set.
Hub-to-spoke channel. Heartbeats carry a per-hive bearer key derived from the hub master secret and are compared in constant time. The payload is telemetry only: health, version, agent and governor summaries and 24-hour token counts. No credential leaves a spoke in a heartbeat. The hub delivers configuration, including App credentials for hosted spokes, in the response.
A green check is necessary but not sufficient. Between green CI and a merge, Hive runs deterministic gates that do not depend on the agent's own claims:
| Gate | Refuses |
|---|---|
| Relay authorization | A merge request without an expected commit, or for a pull request not on the merge-eligible list at that commit, or from a user whose mode cannot merge. |
| Automerge preconditions | Draft, closed, not mergeable, hold, needs-human, needs-rebase, do-not-merge, blocked, hive-pause/<hive-id>; CI not green; a current CHANGES_REQUESTED review; a missing reviewer verdict when required. |
| Fresh fetch | Merging on cached state: the head commit is re-fetched and re-verified immediately before the merge call. |
| No-CI repositories | Merging where no checks exist unless auto_merge.no_ci_ok is explicit. |
| DCO | Merging a head whose DCO check is not passing. |
| Trusted-author automerge | Auto-merging a human or bot pull request unless the author is a trusted author with a merger or owner role and GitHub write access; permission lookup failures fail closed. |
| Intent verification | A pull request with no linked issue; a feature with no approved plan; any change to workflows, the gh wrapper, proxy rules, policies, hive.yaml, OWNERS or CODEOWNERS without maintainer approval. |
| Hold guard | Lifting a hold onto a head that moved since the human saw it; drift re-applies hold and posts one comment naming the new commits. |
| Review swarm verdicts | A self-asserted approval; verdicts are written by the review relay into a hive-owned directory and aggregated deterministically. |
| Escalation circuit breaker | A fourth fix attempt after three distinct red commits; the item is labelled and routed to a person. |
| Stage engine | Any writer of stage/* labels other than src/pkg/stageengine; an admission test enforces this. |
| Sentinel label | Hive approval and every automerge lane while sentinel-alert is present. |
| Repo pause | Agent writes, relays and automerge on a paused repo. |
| GitHub | Hive never force-merges; branch protection and rulesets apply to the App token as to a human. |
Every merge leaves a review evidence bundle: canonical JSON of what was
reviewed and which checks and verdicts were seen, hashed and optionally
Ed25519-signed. See review-evidence.md. Check the
enforcing mode: intent.enforce: true blocks; shadow and report-only modes
do not.
- Reporter trust (opt-in) withholds issues from authors outside the trusted set until a maintainer adds a triage label, and holds pull requests that trace to unaccepted issues. See securing-your-hive.md.
- Dashboard roles.
authorized_userscarriesread,read-write,mergerorowner. Security settings, sandbox toggles and merge-lane releases are owner-only. - Contributor tiers. Relay contributors move from
newcomertocontributorautomatically after five completed pull-request tasks, totrustedby operator grant, and tomergeroradvisorby maintainer decision. Tiers do not decay. See contributor-trust-and-roles.md. - Claims and leases are fenced by task generation, so no issue is held by two contributors at once. The lease protocol is formally modelled.
- Author kind, not author claim. Pull-request authors are classified from GitHub identity (Hive App, trusted bot, human, unknown bot).
- Issue commands (045). A human with repo write/maintain/admin access
can use
/hive approveor/hive decision <direction>to release decision parking. The command liftsneeds-human, whoever applied it, but neverhold. Label-driven repos use their configured acceptance labels instead. - PR commands (085/070). Bare
/hive approveis acknowledged only. On an eligible Hive-authored PR,/hive decision <instruction>routes the full text to the author/fixer./hive decision approve <rationale>records approval for the current head and can releaserequires_human. This requires repo write access or higher and configured merger trust. Other authors use GitHub reviews/manual merging. Commands do not waive CI, holds, author admission or path fences. See the exact gate contract. - Owner self-nomination is a sentinel rule: a pull request adding its
author to
OWNERS,CODEOWNERSorMAINTAINERSis flagged and blocked.
Sentinel (default on) checks every open pull request against eight rules:
sensitive paths, owner self-nomination, permission escalation in workflows,
secret exposure, CI gate weakening, test removal, security policy edits, and
remote code execution patterns. A match applies sentinel-alert, posts one
comment and writes an audit entry. The label blocks Hive approval and every
automerge lane until a maintainer removes it.
Whether that label and comment reach GitHub is decided by the write-back
containment gate (pkg/writeback): on a PR Hive did not open, sentinel
writes need ACMM L5 plus the review opt-in label (L6 without it), the repo
must not be in issues-only/off mode, and the PR must not predate Hive's
write access to the repo (backfill guard). Below the gate the finding is
recorded, audited as sentinel-finding-suppressed, and shown in the
Security tab and /api/sentinel — the scan never stops, only the
unsolicited write does. The same gate fronts hold-gate notices, stage
labels, supersession and duplicate-fix notices and reporter-trust holds; a
ratchet test fails on any new direct GitHub write outside the package.
Trajectory review runs every 600 seconds by default. A second model compares each agent's assigned intent with the last 120 lines of its rendered terminal transcript and pauses the agent on divergence. It fails open if the reviewer is unavailable.
Audit trails. The dashboard audit log records every dashboard and API
mutation, merge decision, sentinel finding and watchdog action to
/data/audit.jsonl, rotated at 5 MB with three backups and a 90-day
retention. The token-access log records which agent used a credential for
which command. Proxy decisions, review evidence bundles and scrubbed agent
transcripts complete the set. See audit-log.md and
token-access-log.md.
Budgets and caps. A seven-day token budget warns at a configurable percentage and suppresses tasks on exhaustion. Fair-share scheduling spreads tasks across repositories; every sweep that writes labels or comments has a per-pass cap. Fix cycles share a re-engagement limit.
Alerts. Sentinel findings, trajectory pauses, crash loops and
needs-human routing appear as dashboard banners and, when configured, as
notifications.
Hub-routed dashboards. Each hosted hive has its own hostname. The hub
authenticates every request (GitHub, Google or a configured OIDC provider)
and returns 403 unless that user has a grant on that hive. On success it
injects the verified identity as headers that the spoke re-verifies. Grants
carry read, read-write, merger or owner.
Direct-route spokes enforce their own authentication: GitHub device-flow
login against a per-hive allowlist, per-user opaque sessions in HttpOnly
cookies, forged identity headers stripped, and the shared bearer token
disabled for user login.
Hosted isolation. One namespace, one pod and one volume per hive. The per-hive Role is namespace-scoped and limited to the hive's own Secret. Internal server-to-server calls carry an auth token compared in constant time.
Keys. Sessions and single sign-on are verified with Ed25519 signatures only; there is no symmetric fallback, and a missing key fails closed. Every spoke uses keys derived per hive from the hub master secret. The master secret supports two generations, current and previous, with a seven-day verify-only window; rotation is triggered by an admin endpoint and spokes converge through a 15-minute reconcile sweep. Setting a fresh master secret directly strands every spoke.
Webhooks and terminals. GitHub webhooks are verified with HMAC-SHA256
against X-Hub-Signature-256. Terminal access uses short-lived signed
assertions. Systemd units refuse to run code from a directory an
unprivileged user could have created.
Sessions. With dashboard.sessions.enabled (default on; Settings →
Dashboard → Inception (spek) sessions, overridden by HIVE_SESSIONS_ENABLED,
false turns it off) the dashboard
offers interactive CLI terminals (/api/sessions, API
reference). A session is a plain vendor CLI, never
a shell, launched with none of the permission-bypass flags agents run with, so
the CLI's own approval prompts stay on. The isolation model, in order of
importance:
- Its own unprivileged uid. Each session's tmux server and CLI run as a uid
from a reserved range (
HIVE_SESSION_UID_BASE, default 20001, withHIVE_SESSION_UID_SLOTSslots) that cannot collide with agent uids (HIVE_UID_BASE, 2001 upward) or the hive's own, through the samesu-exechop agents use. The slot is allocated by the dashboard store, persisted in the session record and reused on resume; the runtime refuses a range that overlaps the agent uid map and recovers a session's uid from the owner of its home directory, never from the id. The uid has its own gid, is not in groupnode(all agents) and not inhive-launch(su-exec), so it cannot read/secrets/*.pem,/data/secrets,/data/.hive, the shared vendor logins in/data/home(group-only, 2770, re-asserted by the entrypoint), the hive's/proc/<pid>/environ, or another session's sandbox, and it cannot reach another session's tmux server. - A private sandbox.
HIVE_SESSIONS_SANDBOX_DIR(default/data/session-sandbox) holds oneroot:hive-launch 0751directory per session with session-ownedhome,work(uploads) andtmpbelow it, so the session cannot replace its own top-level directories and the hive reads transcripts for resume only through the launcher group. Deleting or pruning a session removes the sandbox and the uid's tmux socket directory before the slot can be reused; if removal fails the record and slot are kept and retried. - A shared clone, a worktree per session, no shared credential. The hive
keeps one per-repository clone (
HIVE_SESSIONS_WORKSPACE_DIR, default<sandbox root>/workspace/<org>/<repo>) that it clones once as itself, with a short-lived App token in a one-shotgit -c credential.helperfile removed right after, so neither the clone's config nor its remote holds a credential; root then hands the tree to the sessions-only group (HIVE_SESSIONS_GID, default 20000) asroot:<gid> 2770, group read-write, nothing for "other". That group is every session's single group (su-exec gives a numeric uid exactly one), which is what lets sessions share the clone's objects and branches; it is refused when it is the hive's own group, the reader group or inside the session uid range, and session sandboxes stayhive-launchgroup-only, so sessions still cannot read each other's homes. The hive itself runs asdev, which is never in that group, so it cannot look inside the clone or a worktree: every check of what is in them runs in a script as the session's own uid. Each session opens in its own git worktree of that clone,<workspace>/.sessions/<id>/<org>/<repo>on branchhive-session/<id>: the hive makes the directory under hive-owned0711parents, root only hands that one empty directory (never one another session already owns) to<session uid>:<gid> 2770, and the session uid itself runsgit worktree add. Git never runs as root in the clone.spektacular initruns in the session's worktree as the session uid. - The shared clone's git config and hooks are locked. Before any session
gets a worktree of a clone, and once per clone at every boot (which fixes a
clone made by an earlier release), root rewrites the clone's
.git/configfrom scratch, without running git, asroot:<gid> 0644, and empties.git/hooks,.git/infoand.git/modulesintoroot 0755directories.extensions.worktreeConfigis on, so a person's own settings go ingit config --worktree, the worktree's ownconfig.worktree, which only that session's uid can write. Root-owned placeholders take the names a session could otherwise create to redirect or configure git (.git/config.worktree,.git/commondir).objects/,refs/andlogs/stay setgid group-writable, so commits, branches and fetches work..git/worktrees/,.gitand the clone directory are3770: a session can add its own entry, but the sticky bit stops it from renaming or replacing anything root or another session owns there. A session's entry under.git/worktrees/is created with no group write, even whilegit worktree addis still checking it out. A session's pane gets nosafe.directory, because its worktree is its own; git's ownership check therefore refuses a.gitthat another uid swapped into the group-writable worktree. As a result, one session can no longer plant a config entry, hook, filter driver,core.fsmonitoror alias that runs as another session's uid, whether in that person's own git or in the git the hive runs for them. The hive's own git always passes-c core.hooksPath=/dev/null -c core.fsmonitor=false. Before the add and remove scripts run git in a worktree, they check (as the session uid) that its.gitfile, its entry under.git/worktrees/and that entry'scommondirare the session's own and lead back to the clone; if they don't, the scripts refuse. What stays shared is data, not code: any session can still read, write or delete the shared objects and refs, and a branch another session made. A worktree is group-writable, so another session can edit or delete its files. The worktree keeps one person's working tree, checked-out branch and spek workflow state (.spektacular/) apart from another's; it is not a defence against a session that sets out to corrupt shared data. The lock also costs these, by design: writes to the shared config fail (git push -uandgit branch --set-upstream-towarn; usegit config --worktree), deleting a ref that is still in the clone'spacked-refsfails (for example a remote-tracking branch thatgit fetch --prunedrops; session branches are never packed), gc and maintenance are off, submodules can't be initialised, and hooks only run from a path the session names withgit config --worktree core.hooksPath. - Deleting a session never silently drops its work. The removal script
runs as the worktree's owner uid. It auto-saves anything uncommitted
(untracked files included, ignored ones not) as a commit on the worktree's
branch, keeps a detached
HEADashive-session/<id>-detached, then deletes the worktree's entry, prunes, and keeps any branch the clone'sHEADlacks. If git fails, the removal fails, and the record and uid slot are kept for a retry. The periodic sweep removes the worktrees of sessions whose record is gone. It does not run while the sessions store has failed to load, or while an unreadable copy is set aside for recovery, so an empty-looking store can't remove every worktree. Pushing from a session uses the person's own login; the hive's token never enters a session. - Environment. Built from an allowlist: no dashboard token, terminal, hub, heartbeat, ttyd or attach-key secret and no GitHub token reaches it.
- Logins are read-only copies, not links. A fixed allowlist of bare login
files (
.claude/.credentials.json,.copilot/config.json,.gemini/oauth_creds.json,.gemini/google_accounts.json,.codex/auth.json,opencode/auth.json) is copied into the session home mode 0400, session-owned.settings.json, hooks, MCP or extension config,gh'shosts.ymland~/.configare never bridged, so a session can neither rewrite shared configuration nor plant a hook an agent would run. - Terminal access is bound. ttyd listens on loopback without a secret a
session uid could not read (its
-ccredential is visible in/proc), so session attaches are gated by a per-session token, HMAC-SHA256 of the tmux session name under a per-bootHIVE_TTYD_ATTACH_KEYthat only the hive and ttyd hold. The dashboard proxy appends it after authorising the request;ttyd-tmux.shrefuses anyhive-sess-*attach without a valid token, refuses a socket not owned by a reserved session uid and runs the attach with a scrubbed environment. No key means no session terminal. A handoff code minted for a session is bound to that session id and its caller (anyone who may see the session) and opens only?arg=hive-sess-<id>; an agent-terminal code never opens a session and still needs owner or read-write. - One keyboard at a time. Every attach is read-only (
tmux attach-session -r) unless the proxy also appends the session's write token, a second HMAC under the same key (hive-ttyd-attach-rw-v1), which it does only for the one user holding the session's keyboard lease. The browser's request carries a single arg, the session name; an extra arg is rejected as malformed before it reaches ttyd, andttyd-tmux.shtreats a missing or wrong write token as read-only, so a viewer cannot promote itself. The creator holds the keyboard from the start; owners and the creator may take it at any time, another read-write user only after it is released or the holder has been idle forHIVE_SESSIONS_KEYBOARD_GRACE_SEC(default 60). Taking it detaches the previous holder's writable tmux client immediately. - Ownership. A session is private by default: only its creator and owners
can list, read, watch, type into or upload to it. The creator or an owner may
set
shared, which lists it for every role (the read role gets the token-redacted scrollback and a read-only live terminal, never the keyboard, Send or upload) and lets read-write users Send, upload and take the keyboard. Renaming, closing, resuming, deleting and thesharedflag stay with the creator and owners. Ids of sessions a caller may not see are never disclosed. - Resume ids never start with
-and a resume command may carry only the vendor binary, a fixed set of resume words and a flag-free id, so a planted transcript name cannot add--dangerously-skip-permissions. - Voice notes stay in the browser. The input bar's Voice button (write
roles only) uses the browser's Web Speech API, so transcription is done by
the browser vendor's speech service (Chrome sends the audio to Google), not
by Hive; the audio never reaches the Hive backend. The transcript only fills
the Send textarea and goes through the same queued
/inputpath as typed text when the user presses Send. To allow it, the gateway'sPermissions-Policyfor the dashboard document isgeolocation=(), camera=(), microphone=(self)(src/deploy/nginx.conf,map $uri $hive_document_permissions_policy); the ttyd terminal iframe (/terminal/) and/api/responses keepmicrophone=(), and no other origin is ever granted the microphone. The same document policy carriesdisplay-capture=(self)for Inbox ● Record's tab audio (inbox-recording.md);/terminal/and/api/keepdisplay-capture=().
Audit: session_created, session_started (the outcome of the background
start), session_closed, session_renamed, session_input and
session_upload record the user and session id (never input text).
session_input is written when a queued Send is actually typed into the pane,
as the user who queued it, so attribution follows the sender, not the moment
of delivery. session_keyboard records every keyboard hand-over (from,
to); since only the holder's attach is writable, keystrokes typed inside the
terminal are attributable to the holder of record at that time. Keystrokes are
still not logged individually.
Operator requirements the code cannot enforce: the container needs the
su-exec helper with CAP_SETUID, CAP_SETGID and CAP_CHOWN (the standard
agent layout; a rootless or single-uid runtime cannot run sessions and they fail
closed). /proc should be mounted hidepid=2 (or the pod run with a
non-dumpable, PID-namespaced layout) where possible: ttyd's command line
exposes its basic-auth credential to every uid, and agent terminals on the same
loopback ttyd are not covered by the session attach token, so a session user on
a hive that also runs agents can still reach them there until ttyd moves to a
credential only the hive can read. Reserve HIVE_SESSION_UID_BASE above every
agent uid and keep /data and /data/home closed to "other".
Dashboard headers. Content Security Policy, X-Frame-Options and related
headers are always set. The metrics endpoint is off unless
HIVE_METRICS_ENABLED is set.
Supply chain. Global npm installs run with --ignore-scripts. Base
images are pinned by digest. Tools such as tmux, ttyd, gh, goose and
su-exec are checksum-verified at build. Third-party Actions are pinned to
commit SHAs. CI runs govulncheck, gosec and golangci-lint as separate
jobs; the agent image ships the same pinned govulncheck and gosec so the
sec-check lane runs them on Go targets inside the pod without downloading
anything (GOVULNCHECK_VERSION, GOSEC_VERSION in src/Dockerfile).
CI also runs OpenSSF Scorecard, Dependabot, an Action-pin check, a setuid inventory
check, DCO trailer checks, a documentation link check and formal-model
checks. Image attestations are turned off because they broke
multi-architecture manifests, and a guard workflow keeps them off. An SPDX
software bill of materials per image is attached to each release
(releases.md). Container images are not signed.
.github/CODEOWNERS covers the security-sensitive paths but is advisory
until code-owner review is required in branch protection.
- ACMM is the autonomy dial. Merge permission is not minted below L6.
L5 adds a
holdlabel on every agent pull request. See acmm-policy-matrix.md. - Issue decision parking is 045. A person with repository write access or
higher answers with
/hive approveor/hive decision <text>, unless the repo uses label-driven acceptance. This releases decision parking andneeds-human, nothold. - PR decision parking is 085. A trusted merger's GitHub Approve
review must name the current head to clear the enforcing sweep gate.
It can override any swarm outcome, including a request for changes;
the audit records who overrode what. On eligible Hive-authored PRs,
/hive decision approvecan answerrequires_human, while other decision text sends work to the fixer. Bare/hive approvenever releases a PR. The detailed command boundaries above still apply. - Owner-only security settings. Changes to
ioscan, intent enforcement, review requirements and the agent sandbox require theownerrole. - Emergency stops are not interchangeable. To stop merging, disable automerge per repo, apply an item hold, or drop below L6. Pausing an agent or freezing the watchdog does not stop the App from merging existing PRs. Use the L6 emergency-stop table to choose the right boundary.
- Hooks run only vetted actions from a fixed set (hooks.md).
- Advisory digests are pinned to one analysed commit; findings whose file no longer exists are dropped.
- Rootless containers cannot enforce the egress gate.
- The proxy inspects GitHub API traffic only. Other destinations are tunnelled. Use Kubernetes NetworkPolicies for full egress control.
- The L5
holdlabel is applied by agent policy. The hard guarantee at L5 is the withheld merge permission, not the label. - Cloud CLI credentials are shared with the CLI. The placeholder-key isolation applies to inference-gateway keys only.
- DCO is policy-driven inside Hive. Enforce it repo-side for a hard guarantee.
- Agents share one container. Per-user separation is not per-task containers. The sandbox is opt-in and two-gated.
- Container images are not signed.
- No CodeQL or container CVE scan runs in this repo's CI.
- Branch protection is GitHub's. Hive does not configure or verify it.
- Gate-integrity invariants are a proposal. Refusing agent force-pushes and history rewrites is designed (design/gate-integrity-invariants.md), not enforced.
- Hub registration has no review step. Any spoke with the derived keys can register.
- Trust tiers do not decay.
- Trajectory review fails open; the
ioscanclassifier fails open only at L1–L4. At L5–L6 text is withheld when the classifier cannot answer. The deterministic rules, canaries, proxy and token tiers hold when a model is down.
Use an owner-authorized session. Keep production inspection read-only. Do not paste tokens, environments or Secret contents into reports.
| Question | Check |
|---|---|
| Is the egress gate enforcing? | Boot log has no HIVE_PROXY_ADVISORY_OK warning; iptables -t nat -L HIVE_PROXY in the pod lists the port-443 redirect. |
| Are agents separated? | cat /var/run/hive/uid-map.json; ls -l /usr/local/bin/su-exec shows -rwsr-x--- root hive-launch; find / -perm /6000 -type f lists only su-exec. |
| Does an agent hold a usable token? | GET /api/config/governor → security.credentialInjection. |
Is ioscan on, and in which mode? |
GET /api/config/governor → security.ioscanEnabled, ioscanFailMode, ioscanCanaries. |
| Is trajectory review on? | GET /api/config/governor → trajectory. |
| Is the sentinel on? | sentinel config and recent findings with the alert label. |
| Who merged what, and why? | GET /api/audit; hivectl evidence export --repo <o/r> --since <date>. |
| Who used a token? | /var/run/hive-metrics/token-access.jsonl. |
| What is the merge posture per repo? | hive.yaml → acmm_level, project.repo_policies[].auto_merge, auto_merge.trusted_authors, project.paused_repos. |
| Are webhooks authenticated? | GITHUB_WEBHOOK_SECRET is configured; test unsigned-request rejection only in a disposable hive. |
| Is the image what CI built? | GHCR digest from the docker.yml run equals the running imageID. |
To test denials, use a disposable evaluation hive and an operator-owned test
repository. A write to a repository outside the allowlist must return 403
with X-Hive-Proxy-Blocked; a request authenticated with a placeholder token
must fail; an unsigned webhook must be rejected. Never probe production by
relaxing gates.
Hive holds no SOC 2, FedRAMP, ISO 27001 or other certification. compliance.md maps the controls above to SOC 2 requirements and lists the requirements Hive cannot cover.
Follow SECURITY.md: use GitHub private vulnerability reporting from the repository's Security tab, or contact a maintainer directly. Do not open a public issue.