Why Agents Need a Control Plane

An agent that provisions infrastructure by emitting shell commands is operating open-loop: every docker run, helm install, or aws cli call is a one-way bet that something else will notice if it goes wrong. Three failure modes dominate:

1. Non-reproducibility. Two runs of the "same" instruction produce different states depending on what already exists on the machine.
2. No drift semantics. When reality diverges from intent, there is no definition of intent to diverge from — so recovery is guesswork.
3. Blast radius. A hallucinated flag or a mis-scoped credential acts directly on the substrate, with nothing between the model output and production.

Nanokit's premise is different: the agent decides what to do; Nanokit guarantees that what the agent decides gets done — deterministically, securely, and reproducibly.

The division of labor

Concern	Owner	Mechanism
Intent	Agent (or human)	Edits nanokit.yml
Planning	Nanokit	Diff desired vs. current state → typed plan
Execution	Nanokit	Ordered, dependency-aware apply with health gates
Verification	Both	Machine-readable state after every operation

The agent's surface area shrinks to two verbs: declare (write the contract) and observe (read structured state). Everything in between — locking, ordering, secret resolution, rollback, drift repair — is Nanokit's job and does not depend on the agent getting it right.

What this buys you

• Idempotence as a property, not a discipline. Applying the same config twice converges to the same state; the second run is a no-op by drift-hash comparison.
• Reviewable changes. Because intent lives in YAML, every agent decision is a diff a human can read before it happens, not a log line after it happened.
• Constrained authority. The agent cannot do anything the config schema doesn't express. There is no escape hatch to arbitrary commands.

Where to go next

• The Declarative Contract — how nanokit.yml maps to deterministic reconcile.
• Machine-Readable State — what an agent can observe today, and where the programmatic surface is heading.

Direction

Programmatic agent primitives — an MCP server exposing operations like create_environment and a structured get_environment — are on the roadmap and are not shipped yet. Today's integration surface is the config file plus the CLI and bridge WebSocket described in these pages.