BeeverForge core architecture

The box and the quality floor

A job runs in a box: an environment the worker creates for that job and discards afterwards. The box runs the client’s own image with the platform’s tools mounted into it, and it is proven against the project’s own gates before any ticket is picked up.

Box kinds#

Kind	What it isolates
`container`	The default. A throwaway Docker container from the project’s image. It bounds CPU and memory, carries secrets only for the job’s duration and sees only the mounted clone, the toolbox, the guidelines and a cache. It does not isolate the network.
`worktree`	A `git worktree` on the worker’s own machine. It isolates the code state only: no CPU, memory, network or secret isolation. The code describes it as never for untrusted work.
`fargate`	A description of a remote task box only. Its runner is not in this repository; it is supplied by an add-on.

A container box as the worker starts it. Secrets are passed for the job’s duration; the network is not isolated.

A durable job is refused in a box that bounds nothing, unless the project declares that the work is the operator’s own. Further kinds can be added as box.<kind> entry points.

Proving the box#

beeverforge box prove turns the box configuration into a recorded fact (ADR-0037). It runs a fixed sequence and stops at the first fault that later checks depend on, so one cause is reported once, with its remedy:

The image’s tag is resolved to a digest.
The toolbox is checked against the image: an image whose C library differs from the toolbox’s build, such as a musl image for a glibc toolbox, cannot execute the harness binaries and is refused by name.
The image contract: a POSIX shell at /bin/sh, a keep-alive, git, a writable HOME and a writable /workspace. A distroless or scratch image cannot be used.
The box starts, the project’s setup: runs, then its validate: gates run on an untouched checkout of main, inside the box.
The harness is checked: its version, its credentials as seen inside the box, the trust store and whether the harness endpoint is reachable through the box’s network.

The checks of beeverforge box prove, in the order they run.

On a box that runs the client’s image the proof asks no agent anything and spends no harness tokens. On a box with no image, where the harness login is a session on the operator’s machine, it asks the harness for a single word to confirm the login works.

A proof is valid while the image digest, the toolbox and the hash of the project’s setup: and validate: commands are unchanged. On a box with an image the toolbox is identified by its operating system, architecture and C library; on a box with no image a new harness version makes the proof stale. Proofs do not expire by time. The board scan refuses to pick up work for a project whose box has something to prove and no valid proof, and states which of those facts moved. A worktree box has no image; it is gated only on a deployment that declares BEEVERFORGE_OWN_WORK, the runtime where the worker is the operator’s own machine.

An advisory gate that fails during the proof does not hold pickup, unless its command could not run at all.

The toolbox mount#

The harness binaries are not installed in the client’s image. They live in a toolbox that is mounted into each box read-only at /opt/beeverforge-toolbox; the operator’s guidelines are mounted read-only as well. The code states the limit of that flag: read-only bounds an accident, not an adversary, because a process running as root in the box can still copy a binary out.

Network egress#

The container box’s network defaults to Docker’s bridge, which is full outbound internet access. Anything the box’s network can reach is reachable by code the agent wrote.

box.network in the registry selects another Docker network, such as a restricted network or one behind a proxy the deployment provides. The core has no built-in allowlist or proxy.
A job needs at least the harness endpoint. A project on a remote forge also needs the forge and the tracker, and whatever setup: installs from package registries.
The proof checks that the harness endpoint is reachable. When a project declares a machine identity, beeverforge doctor probes whether the box can reach the cloud instance-metadata address.
An air-gapped environment cannot run a job, because the coding agent is a remote service.

The quality floor#

The floor is in policy/floor.py: the validation roles test and security are required. Before the implementation pass, after sizing, the runner checks that both roles are present after the cascade of deployment defaults, stack presets, the repository-wide block and per-component blocks. A project missing one is refused with the role named and a remedy; nothing runs.

Every project inherits a security gate from org_defaults/floor.yaml: a scan of tracked files for committed credentials. It is declared advisory: true.
Inheritance only adds roles the project does not declare. A project that declares a role keeps it exactly as written, so it can replace a required role’s command, or make it advisory, and still satisfy the floor. The floor checks that the roles are present, not what they run.
Protected paths are additive: a project can add to the deployment’s list and has no field to remove from it. A change that touches a protected path is never merged automatically.

What advisory: true does. The gate runs and is reported, with a warning mark in the pull request body. It never fails the job, never blocks the merge and never triggers a repair. A profile can promote an advisory gate to blocking, never the reverse.

Separate executor and reviewer#

The reviewer runs in a context of its own. It receives the ticket, the diff, the gate results and the constraints, and is never shown how the change was made or what the executor says it did. The Claude Code reviewer is a fresh, non-resumed session in plan mode; the generic harness reviewer is told that it did not write the code. The code notes that independence is reduced when the reviewer and the executor use the same harness.

The diff is the truth#

ADR-0001 states it as “The label is a guess; the diff is the truth.” The review is given git diff from the measured base to HEAD, computed inside the box. The executor’s own summary goes into the pull request labelled as a claim: no gate checks it and the reviewer is not shown it.

Sealed human gate answers#

A person approves a production release, answers a merge gate or says “not yet” in the panel, which checks the caller before it sends anything. Because anything that can reach the engine could send the same signal, each answer is sealed by gate_seal.py:

The seal is HMAC-SHA256 over the gate kind, the workflow id, an expiry, a nonce and exactly the fields the workflow will act on, such as the version and the approver.
A seal is valid for 600 seconds and for one workflow, and it is spent once.
The worker verifies it in an activity, with a constant-time comparison, before it releases or merges. Any failure counts as no, is recorded where the panel shows it, and leaves the gate open.
The key is BEEVERFORGE_GATE_SECRET when set; otherwise a gate.key file created with mode 0600, beside the registry or in ~/.beeverforge/.

Limits the module documents. The seal proves that a process holding the key sent the answer, not that the panel did. The key is symmetric, so any process that can read it can seal; the panel and the worker’s product role are both legitimate signers. The seal holds against the container box, which never sees the key. It does not hold against a worktree box, which runs as the operator’s user and can read the key file, nor against the judging roles, which on the compose installation run as worktree boxes inside the worker container. Closing this needs an asymmetric seal.

What the seal does change: an unintended path to the engine can read and cancel workflows, but cannot approve a release or land a pull request.