Architecture Overview (25k plan)

Goals

• Enforce all side effects via a policy-aware proxy inside a Firecracker VM (Firecracker driver).
• Treat permission state as a static envelope around a dynamic agent.
• Default network egress to deny; explicit allowlists only (host netns iptables + guest defense).
• The node provisions a per-pod netns, tap interface, and guest IP; guest init configures eth0 from kernel args.
• Netns setup enables bridge netfilter (br_netfilter) so iptables can enforce guest egress.
• Approvals require signed tokens issued by an authority (HMAC today; external authority roadmap).
• Provide verifiable audit logs for every operation (signed + verified).

Trust Boundaries

Agent / Tool Adapter
  |  (signed HTTP)
  v
Host Control Plane (nucleus-node + signed proxy)
  |  (vsock bridge, no guest TCP)
  v
Firecracker VM (nucleus-tool-proxy + enforcement runtime)
  |  (cap-std, Executor)
  v
Side effects (filesystem/commands)

Boundary 1: Agent -> Control Plane

• Requests are signed (HMAC today; asymmetric is roadmap).
• Control plane forwards only to the VM proxy.

Boundary 2: Control Plane -> VM

• Use vsock only by default; guest NIC requires an explicit network policy and host enforcement.
• Host enforcement uses nsenter + iptables inside the Firecracker netns (Linux only).
• By default the guest sees only proxy traffic; optional network egress is allowlisted.

Boundary 3: VM -> Host

• No host filesystem access except mounted scratch.
• Rootfs is read-only; scratch is per-pod and limited.

Components

nucleus-node (host)

• Pod lifecycle (Firecracker + resources).
• Starts vsock bridge to the proxy.
• Applies cgroups/seccomp to the VMM process.
• Starts a signed proxy on 127.0.0.1.

approval authority (host, separate process, roadmap)

• Issues signed approval bundles (roadmap).
• Logs approvals with signatures.
• Enforces replay protection and expiration.

nucleus-tool-proxy (guest)

• Enforces permissions (Sandbox + Executor).
• Requires approvals for gated ops (counter-based today; signed requests required; bundles are roadmap).
• Writes signed audit log entries (verifiable with nucleus-audit).
• Guest init (Rust) configures networking from kernel args and then execs the proxy.
• Guest init emits a boot report into the audit log on startup.

policy model (shared)

• Capability lattice + obligations.
• Normalization (nu) enforces uninhabitable state constraints.

Data Flows

Tool call

1. Adapter signs request (if enabled).
2. Signed proxy injects auth headers (if enabled).
3. Proxy enforces policy and executes side effect.
4. Audit log records action (and optional signature).

Approval

1. Agent requests approval.
2. Proxy records approval count for the operation.
3. Approval count is consumed for gated ops.

Non-goals (initial)

• Multi-tenant scheduling across hosts.
• Full UI control plane.
• Zero-knowledge attestation.

Progress Snapshot (Current)

Working today

• Enforced CLI path via nucleus-node (Firecracker) + MCP + nucleus-tool-proxy (read/write/run).
• Runtime gating for approvals, budgets, and time windows.
• Firecracker driver with default‑deny egress in a dedicated netns (Linux).
• Immutable network policy drift detection (fail‑closed on iptables changes).
• DNS allowlisting with pinned hostname resolution (dnsmasq in netns, Linux).
• Audit logs are hash‑chained, signed, and verifiable (nucleus-audit).

Partial / in progress

• Web/search tools not yet wired in enforced mode.
• Approvals are runtime tokens; signed approvals are required. Preflight bundles are planned.
• Kani proofs exist; nightly job runs, merge gating and formal proofs are planned.

Not yet

• Remote append‑only audit storage / immutability proofs.

Invariants (current + intended)

• Side effects should only happen inside nucleus-tool-proxy (host should not perform side effects).
• Firecracker driver should only expose the signed proxy address to adapters.
• Guest rootfs is read-only and scratch is writable when configured in the image/spec.
• Network egress is denied by default for Firecracker pods when --firecracker-netns=true; if no network policy is provided, the guest has no NIC and iptables still default-denies.
• Monotone security posture: permissions and isolation guarantees should only tighten (or the pod is terminated), never silently relax after creation.
  • Seccomp is fixed at Firecracker spawn.
  • Network policy is applied once and verified for drift (fail‑closed monitor).
  • Permission states are normalized via ν and only tightened after creation.