How Kiwi works — control plane, data plane, and sandbox

Kiwi is a BYOC/managed agentic execution platform written in Go (targeting Go 1.25), persisted on PostgreSQL via GORM. Its design centers on one seam: the components that decide what to do are separated from the components that run untrusted, model-generated code.

The components

Component	Package	Responsibility
Control Plane daemon	cmd/kiwid, pkg/orchestrator	HTTP API, auth, the core engine, webhooks. Runs as split roles.
Planner	pkg/planner	Decompose a task into a DAG of worker specs; persist an immutable manifest; enqueue workers.
Lease queue	pkg/store/queue.go	A Postgres lease-based work queue with DAG-dependency gating and crash recovery.
Store	pkg/store	Postgres models — jobs, manifests, events, checkpoints, agents, sealed credentials, org limits.
Data Plane daemon	cmd/kiwidaemon, pkg/daemon	Pull-model worker: poll, unseal credentials, provision a workspace, run the loop, open a PR.
Actor–Critic loop	pkg/loop	The correction loop: propose edits, optionally review, re-run the test until it passes.
Sandbox	pkg/sandbox	Pluggable isolation for the test command — Docker, gVisor (runsc), Firecracker.
Git cache	pkg/gitcache	Bare clones plus instant git worktree workspace provisioning.
Crypto	pkg/crypto	X25519 credential sealing and Ed25519 heartbeat signing.
Provisioner	pkg/provisioner	Free tier: cold-start a per-org daemon container on submit; scale to zero when idle.
Auth	pkg/auth	Orgs, API keys, per-org limits, provisioning requests.
Provider	pkg/provider	Pluggable LLM interface (Anthropic, Codex, Gemini, or compatible endpoints) plus a mock.

How they connect

The seam that matters

The single most important architectural decision: the LLM Actor and Critic run inside the daemon process; only your test command runs in the sandbox.

That means:

• Model-generated code executes under default-deny networking in the sandbox and never sees the LLM API key (the key lives in the daemon, not the sandbox).
• Credentials are sealed to a specific daemon's public key and only unsealed in that daemon's memory — never written into the sandbox, never persisted to disk in plaintext.
• Kiwi's differentiation is the layer above the sandbox — the planner and the swarm — not the sandbox itself.

Persistence and consistency

• PostgreSQL via GORM. State transitions use strong consistency; a plan's manifest and all its worker tasks are enqueued in a single transaction (no partial plans).
• Migrations are numbered migrations/*.up.sql files applied by RunMigrations, tracked in schema_migrations, and run via kiwid -role migrate. Some tables are managed by GORM AutoMigrate rather than a numbered migration.
• NATS JetStream provides optional durable queuing/event streaming; the Control Plane degrades with a warning if NATS is unreachable. The BYOC daemon handoff itself uses the Postgres lease queue, not NATS.

Split roles

The Control Plane binary runs as one of several roles so the API surface and the background engine can scale independently:

kiwid -role api          # HTTP API only
kiwid -role orchestrator # background engine / sweepers only
kiwid -role migrate      # apply migrations and exit
kiwid -role all          # everything in one process (local/dev)

See The Control Plane / Orchestrator for the roles and the lease queue in detail.