Machine-Readable State

An agent cannot act on infrastructure it cannot see. Nanokit exposes its view of the world as structured data — not log scrapes — through two channels.

What is observable today

State is reported per project and per environment for four resource families:

Family	What state includes
Services	Desired vs. running status, image/config drift, health, exposure
Databases	Engine, mode, branch topology, volume backing
Secrets	Which keys are declared/resolved — never their values
Domains	Declared hosts, TLS/certificate state

Channel 1 — the bridge WebSocket

Every environment runs a local bridge on ws://127.0.0.1:3006. It carries telemetry and accepts request/response messages, so an agent can read live state and trigger guarded actions (e.g. volume maintenance) over a single persistent connection. The protocol is message-based JSON — see UI Bridge (WebSockets) for the wire details.

Typical loop for an agent:

1. Connect to the bridge.
2. Request current inventory (services/databases/secrets/domains).
3. Compare against intent; if a change is needed, edit nanokit.yml (see The Declarative Contract).
4. Re-read state to verify convergence.

Channel 2 — the CLI

The same information is available offline via nkapp:

• nkapp plan prints the exact reconcile plan before anything executes — the cheapest way for an agent to validate a config edit.
• nkapp doctor reports environment health and common failure classes.
• nkapp secrets list enumerates declared secret keys (values are never printed).

Both channels report state, never narrative: consumers get typed fields they can branch on, which is precisely what makes closed-loop agent behavior safe — the loop terminates because convergence is checkable.

Direction — structured state APIs

Today's shape is CLI output plus bridge messages. The roadmap extends this into explicit agent-facing primitives:

• An MCP server exposing Nanokit operations as tools.
• A first-class get_environment call returning fully structured environment state (no parsing), alongside create_environment-style operations.
• A policy engine so guardrails for agent-initiated changes are declarative too.

These are marked as direction: design may change, nothing above is shipped yet.