Skip to main content

The Actor–Critic loop — verifying agent code against your own tests

The Data Plane daemon (cmd/kiwidaemon, pkg/daemon) is the only component that touches your source code and your model key. It is a pull-model worker: nothing connects to it; it polls the Control Plane, does the work, and reports back.

The pull model​

On first boot the daemon generates its keypairs and registers with the Control Plane using a single-use join token (mint one with POST /api/v1/daemon/join-token, or from the dashboard's Fleets page). After registration its persisted identity key is sufficient, and the token can be omitted on restart.

It then heartbeat-polls the Control Plane over HTTPS. Each poll can return a leased worker spec plus that org's sealed credentials. Because the daemon only ever makes outbound HTTPS connections, it runs cleanly inside a customer VPC with no inbound firewall holes — the foundation of the BYOC model.

Workspace provisioning​

Rather than clone a repo for every task, the daemon keeps a cached bare clone per repository (pkg/gitcache) and provisions each worker an instant workspace with git worktree. One job maps to one branch, so sibling workers on the same job share a job branch. The git cache keeps at most -max-cached-repos bare clones (default 20), evicting the least-frequently-used; 0 disables the bound.

The daemon can also discover the target file(s) from the task and infer the test command when they are not given, so a task submitted through the API or dashboard needs only a description and a repo.

The Actor–Critic loop​

The loop (pkg/loop) is deliberately decoupled — it depends only on the LLM provider interface and the local filesystem, so it can run in the daemon or elsewhere without pulling in sandbox, store, or crypto packages. It is driven by one injected function, TestFunc, which runs the verification command and reports (output, passed, err).

Key behaviors, straight from the code:

  • The test is the contract. The loop runs the test first — if the task is already satisfied, editing anything would be wrong, so it stops. A green test is the only definition of done.
  • Actor proposes, Critic reviews. The Actor returns a full corrected file (or a set of files in multi-file mode). The Critic is optional: when present it gates each edit before it touches disk and can send the Actor back with feedback; when absent, the test command is the review.
  • Safety rails. The loop halts on a budget cap (default $0.50/task), a max-steps cap (default 6 iterations), or a stall — the same failing test output repeating three times means the Actor is going in circles, so it stops rather than burn budget.
  • Multi-file safety. In multi-file mode the model's returned paths are mapped back to the input files by exact or path-boundary suffix match, and empty or traversing paths are rejected — a write can never land outside the target set.

Opening the PR​

When the test goes green, the daemon commits the worktree and opens a pull request using the org's git token (unsealed in memory, never written into the sandbox). A SUCCEEDED task always corresponds to a real PR — the daemon treats "green test but no PR" as a failure rather than reporting a misleading success. It then reports completion (with the PR URL) back to the Control Plane, which transitions the task to SUCCEEDED and may unblock its dependents.

Running a daemon​

kiwidaemon -api-url https://api.runkiwi.dev \
    -key-path ~/.kiwi/daemon.key -cache-dir /tmp/kiwi-cache \
    -poll-interval 5s -max-cached-repos 20 -max-steps 6 -max-budget 0.50 \
    -join-token "$KIWI_JOIN_TOKEN"

For the shared Free tier, pass -sandbox-runtime runsc (or set KIWI_SANDBOX_RUNTIME=runsc) so the test command runs under gVisor. See Sandbox & isolation.