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.
Admission (Planner)	ee/planner	Admit a task: org limits, idempotency, fleet routing, model policy; enqueue it. Does not plan its contents — see Admission & the Planner.
Lease queue	pkg/store/queue.go	A Postgres lease-based work queue with crash recovery.
Store	pkg/store	Postgres models — jobs, tasks, events, execution records, agents, sealed credentials, org limits.
Data Plane daemon	cmd/kiwidaemon, pkg/daemon	Pull-model worker: poll, unseal credentials, provision a workspace, run the session, open a PR.
Architect/Implementer session	pkg/session	The execution loop: a persistent Architect plans and reviews each round; an agentic Implementer edits the repository with real tools.
Sandbox	pkg/sandbox	Pluggable isolation for the install and verification phases — 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	ee/provisioner	Free tier: cold-start a per-org daemon container on submit; scale to zero when idle.
Auth	ee/auth	Orgs, API keys, per-org limits, provisioning requests.
Provider	pkg/provider	Pluggable LLM interface (Anthropic, OpenAI, Gemini, or compatible endpoints) plus a mock.
Execution record	pkg/ver	Per-job provenance: daemon-attested, Control-Plane-signed, hash-chained per org.

How they connect

The seam that matters

The single most important architectural decision: the Architect and Implementer 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 Architect/Implementer session — not the sandbox itself.

Persistence and consistency

• PostgreSQL via GORM. State transitions use strong consistency.
• 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.