MicroVM-backed local execution environments

Outcome

A local mecatl session can select an operator-approved microVM execution environment while the agent loop, model providers, permissions, hooks, MCP, identity, memory, and credentials stay in the host harness. Every agent-facing filesystem operation and Bash command executes against the same session microVM namespace.

The first supported deployment is local and single-Unix-user, on Linux amd64/arm64 and Apple Silicon macOS. The design reserves the caller/principal seam needed for future OIDC/SPIFFE enforcement but does not wait on unfinished agent-identity work.

Settled design

• Reuse the execution-environment foundation shipped by #462: tool.Environment, durable/open EnvironmentRef, resolver, Workspace, bound CommandRunner, and environment-aware fork/merge seams remain the engine contract.
• Add a nested Go module under environment/microvm/; it owns the separate mecatl-microvmd binary, go-microvm/libkrun integration, guest agent, OCI/runtime assets, VM lifecycle, networking, and platform-specific code. The normal engine/root dependency graph does not absorb go-microvm or libkrun.
• One parent microVM lives for the session lifetime. Close detaches; explicit deletion/retention destroys; a missing persisted ref never silently creates an empty VM or falls back to local execution.
• A Git source gets a session-owned host worktree. Its staged/unstaged/untracked content is captured according to an explicit, tested fidelity contract. The prepared worktree is mounted RW through virtio-fs at guest /workspace, so edits are immediately visible on the host. Multiple sessions for one repository use different worktrees and VMs.
• Reuse/extract Brood Box's existing linked-worktree reconstruction: guest-local Git metadata plus the common object store mounted separately and host-enforced read-only through the current libkrun virtio-fs API.
• Keep three path roles explicit: request source checkout, prepared host session worktree, and guest execution root /workspace. Host project discovery reads the prepared worktree; user-global config/soul/memory/skills and host MCP/provider credentials remain outside the VM.
• Use a versioned, authenticated guest protocol over vsock for structured exec/stream/cancel and filesystem operations. SSH is bootstrap/debugging only.
• The local control plane uses a private UDS and Linux/macOS peer credentials. Driver records bind Unix owner, session, opaque environment ref, generation, prepared worktree, profile, and immutable artifact identities. A future principal assertion follows #452: identity only, never bearer tokens/scopes/authority.
• Every environment explicitly configures go-microvm's network provider. Guest egress is separately disclosed from host provider/WebFetch/WebSearch/MCP/hooks traffic. Initial policy closes the current IPv6 gap either by disabling guest IPv6 or by complete filtering.
• Execution images, go-microvm runtime, and firmware are digest-pinned and verified against operator-configured signatures and attestations. Reuse go-microvm's existing pinned libkrun/libkrunfw release artifacts and build pipeline.
• environment_profile is separate from the existing tool-surface profile. Profiles are strict and operator-only. Schedules and remote/multi-user deployment are deferred.

Existing foundations and dependencies

Already landed and usable:

• #462 execution environments and #514 durable reattachment.
• #367 caller/owner identity.
• #368's implementation via PR #501, despite the issue still appearing open.
• #375's key-reachability result, which motivates removing model-controlled Bash from the harness namespace.
• go-microvm v0.0.39 pinned to libkrun v1.19.4 and libkrunfw v5.5.0.
• Brood Box v0.0.24's Linux/macOS VM runner, RW virtio-fs workspace, OCI cache, egress integration, and linked-worktree reconstruction.

Not blockers for this local first phase:

• #452 becomes required for remote/multi-user enforced drivers.
• #440/#478 become relevant if mecatl-issued signed filesystem grants are added.
• #369/#370/#371/#372/#373/#376 remain later sensitivity, sharing, attenuation, external-authority, schedule, and escalation work.

Observable completion

• Two concurrent mecatui sessions opened from one repository run in distinct host worktrees and distinct VMs; edits from each guest appear immediately in its host worktree and cannot affect the sibling working tree or Git metadata.
• Read/Edit/Write/Grep/Glob and Bash all observe the same guest /workspace state and preserve mecatl's read-version/create-only/conditional-replace guarantees.
• The guest cannot access host provider/MCP/identity credentials or unrelated host paths; only explicitly materialized/mounted assets are visible.
• Guest egress allow/deny rules are fail-closed and tested on every supported platform; host-side network surfaces are disclosed separately.
• A restarted harness reattaches the exact session environment generation. Unknown, stale, foreign, or destroyed refs fail loudly without local fallback.
• Runtime, firmware, and execution-image verification fails closed on wrong digest, signer, missing attestation, or stale policy.
• Linux amd64/arm64 and Darwin arm64 live E2E cover boot, filesystem, exec streaming/cancellation, networking, detach/reattach, and deletion.
• Default non-microVM behavior and the public engine dependency closure remain unchanged.

Non-goals for the first delivery

• Remote/cluster VM placement or multi-user driver enforcement.
• MicroVM-backed schedules.
• Unified guest+host network containment.
• Moving MCP/provider credentials or the LLM agent loop into the guest.
• Cross-principal environment sharing.
• Replacing mecatl's permission or trust policy with backend policy.

Delivery process

This is capability-scale work. A draft acceptance plan under docs/acceptance/ is the verification contract and lands with the implementation through the accumulator-branch /plan-orchestrate flow.