Date: 2026-09-02 Status: current planning authority. The historical foundation that follows is retained for architectural context; where it conflicts with this section or docs/1.0-scope.md, the current Developer Environment mission wins.

vz delivers reproducible, parallel Developer Environments. A project defines a topology that can be instantiated many times, including several times for one worktree. Each Environment is an isolation/lifecycle aggregate containing one or more target-native Machines plus owned storage, networks, endpoints, policy, and evidence. Sandboxes, VMs, containers, and resident agents are mechanisms.

Lockdown remains a selectable policy and sandboxing remains a powerful implementation primitive. Neither is the primary product value. The default Developer profile favors complete, reproducible development workflows and safe parallelism on local hardware.

Implementation and conformance proceed in this exact order:

Linux is universal: macOS, Linux, and Windows hosts all gain the Linux Machine target. Native macOS is immediate; native Windows is last.

Each host×Machine-target pair earns support through real end-to-end evidence. Shared lifecycle semantics do not imply identical backend capabilities.

• One project or worktree may have several named Environments; each Environment may have several target-native Machines.
• Definitions and artifacts are reproducible, pinned, checksummed, inspectable, repairable, and portable wherever the same target contract is supported.
• Mutable state and networking are isolated per Environment; Machine-owned target state and capabilities are additionally isolated per Machine.
• Machines communicate only through declared private/public-like paths. Separate Environments are default-deny except for explicit service peer grants.
• VMs, OCI containers, native isolation, pools, sandboxes, worktrees, harness residency, brokers, and shims are internal primitives or optional environment capabilities.
• Humans, local agents, IDEs, scripts, CI jobs, and orchestrators use the same lifecycle and capability truth.
• Target-specific behavior is declared through versioned capabilities and fails closed when unavailable.

Docker compatibility is implicit for every Developer-profile Linux Machine on a host×Machine-target pair that has passed conformance. It is Machine-scoped, never Environment-global:

• every Linux Machine owns its own Engine, containerd, BuildKit cache, images, volumes, networks, credentials, data root, endpoint, and Docker context;
• the normal host Docker CLI, Compose, and buildx select one exact Environment/Machine;
• vz never mutates the user's default Docker context and never falls back to Docker Desktop, system Docker, or another environment;
• concurrent environments must have no Docker state, socket, network, port, or lifecycle cross-talk;
• native macOS and native Windows Machines do not inherit Docker claims from Linux Machines.

Current planning follows the Developer Environment topology contract and ordered host×Machine-target matrix. Existing backend work is retained beneath it; historical nouns do not define the current product API.

Historical context (pre-Developer Environment mission). This plan originally scoped vz as a macOS Virtualization.framework library for sandboxing coding agents in native macOS VMs. Its FFI, async VM, vsock, VirtioFS, signing, and native-macOS research remains relevant. Product statements such as “sandbox is the product,” “macOS host only,” “long-lived single VM,” and “agents cannot use Docker inside the guest” are not current scope constraints.

vz is a Rust-native library for Apple's Virtualization.framework, purpose-built for sandboxing coding agents in macOS virtual machines. It provides a safe async Rust API over the framework's Objective-C classes, a high-level sandbox abstraction for agent runtimes, and a CLI for standalone use. The goal: any coding agent on macOS (Claude Code, Codex, OpenCode, Aider) gets full OS-level isolation in a native macOS VM with sub-10-second restore times and zero network configuration.

Every coding agent running on macOS needs sandboxing. Agents execute arbitrary code, install packages, modify filesystems, and make network calls. Without isolation, a single hallucinated rm -rf / or exfiltrated credential is catastrophic.

Why Linux VMs don't solve this. Tools like Vibe, VibeBox, and Claude Cowork run agents in Linux micro-VMs. But macOS development requires macOS: Rust binaries compiled for darwin, Xcode toolchains, SwiftUI previews, macOS-specific APIs, Homebrew packages. Cross-compiling from Linux adds friction and breaks half the toolchain.

Why existing macOS tools don't solve this:

• Seatbelt (sandbox-exec) — Deprecated by Apple. Process-level only, no filesystem isolation, no network domain filtering, known escape vectors. Not suitable for adversarial workloads.
• Tart — Excellent macOS VM manager for CI, but written in Swift with no Rust API. Designed for ephemeral clones, not long-lived sandboxes with fast session turnover. No vsock-based communication channel.
• Docker — Runs Linux containers on macOS via a hidden Linux VM. Same cross-compilation problem. Not native macOS isolation.
• Kata Containers / Firecracker — Linux-only hypervisors. No macOS guest support.

There is no Rust library for running macOS VMs as coding agent sandboxes. vz fills that gap.

┌─────────────────────────────────────────────────────┐
│                     vz-cli                          │
│  `vz run --image base --mount project:./workspace`  │
├─────────────────────────────────────────────────────┤
│                   vz-sandbox                        │
│  Pool, Session, Channel, Guest Agent binary         │
├─────────────────────────────────────────────────────┤
│                      vz                             │
│  Safe Rust: Vm, Config, VirtioFs, Vsock, SaveState  │
├─────────────────────────────────────────────────────┤
│              objc2-virtualization v0.3.2             │
│  Auto-generated bindings to ALL Vz.framework classes│
├─────────────────────────────────────────────────────┤
│           Apple Virtualization.framework            │
│              (macOS 14+ / Apple Silicon)            │
└─────────────────────────────────────────────────────┘

┌─────────────── HOST ───────────────┐     ┌─────────────── GUEST ──────────────┐
│                                    │     │                                     │
│  Agent Runtime (HQ, Claude Code)   │     │  Guest Agent (vz-guest-agent)       │
│       │                            │     │       │                             │
│       ▼                            │     │       ▼                             │
│  vz-sandbox::Channel               │     │  vsock listener (port 7424)         │
│       │                            │     │       │                             │
│       ▼                            │     │       ▼                             │
│  vsock (port 7424)  ◄──────────────┼─────┼──  vsock device                     │
│                                    │     │                                     │
│  VirtioFS share ────────────────── │ ──► │  /mnt/workspace (auto-mounted)      │
│  (host: ./my-project)              │     │  (read-write project files)         │
│                                    │     │                                     │
└────────────────────────────────────┘     └─────────────────────────────────────┘

Communication:  vsock — length-prefixed JSON frames (no SSH, no network config)
File sharing:   VirtioFS — near-native performance, configured at VM creation

• vz wraps objc2-virtualization in safe async Rust. It owns VM lifecycle (create, start, pause, stop, save, restore), configuration building, VirtioFS mounts, and vsock streams. All ObjC completion handlers are bridged to tokio futures. All VZVirtualMachine operations are dispatched through a serial dispatch queue (mandatory Apple requirement).

• vz-sandbox provides the high-level abstraction: a pool of pre-warmed VMs, session lifecycle (acquire a VM, mount a project, execute commands, release), and a typed Channel protocol over vsock. It also contains the guest agent binary that runs inside the VM.

• vz-cli exposes vz-sandbox functionality as CLI commands for standalone use without writing Rust.

The objc2-virtualization crate (v0.3.2) provides auto-generated bindings to ALL Virtualization.framework classes. These bindings are mechanically generated from Apple's headers by the objc2 project, covering every class from VZVirtualMachine to VZVirtioSocketConnection. This eliminates the need for a separate vz-sys crate with hand-written FFI bindings. The vz crate wraps objc2-virtualization directly with a safe, ergonomic API. The project has 3 crates, not 4.

All Virtualization.framework operations use Objective-C completion handlers (blocks). We bridge these to Rust futures using block2 to create the ObjC block and tokio::sync::oneshot to deliver the result. Every public method on Vm returns a Future. The runtime is tokio.

Apple requires that ALL VZVirtualMachine operations (start, stop, pause, resume, save, restore, delegate callbacks) execute on the same serial dispatch queue. This is not optional — violating it causes undefined behavior or crashes. We use the dispatch2 crate to create a serial queue per VM and ensure every ObjC call is dispatched through it. This is the single most important correctness requirement in the crate.

Save/restore (saveMachineStateTo:completionHandler: / restoreMachineStateFrom:completionHandler:) was introduced in macOS 14. Without it, every sandbox session requires a full 30-60s macOS boot. With it, restore takes 5-10s. This is essential for the sandbox use case, so we set macOS 14 as the floor.

Rather than ephemeral clone-and-boot (Tart's CI model), vz uses a single long-lived VM. The VM boots once (or restores from saved state), then serves sessions sequentially. Project directories are swapped via VirtioFS mounts. This avoids the 2-VM kernel limit being a bottleneck, eliminates boot penalties, and sidesteps APFS clone management.

vsock (AF_VSOCK) provides a socket interface between host and guest without any network configuration. No IP addresses, no SSH keys, no port forwarding. The host connects to the guest (or vice versa) using a simple port number. This maps perfectly to tool-forwarding architectures where the host holds secrets and the guest holds only stubs.

stdout/stderr from guest command execution is streamed to the host as vsock frames in real time. The guest agent pushes output as it arrives rather than the host polling for it. Frame format: 4-byte little-endian length prefix followed by a JSON payload containing the stream type (stdout/stderr/exit) and data.

Performance and reliability claims must be backed by reproducible benchmark evidence. Any headline claim (startup time, restore time, pull speed, convergence latency, or density) must include the exact host/software baseline, benchmark method, and raw artifacts needed for independent verification.

Build the safe Rust wrapper. This is the foundation everything else depends on.

• Dispatch queue management (serial queue per VM, dispatch2 crate)
• Async bridging pattern (ObjC completion handler to tokio future via block2 + oneshot)
• VmConfigBuilder: CPU count, memory, boot loader, disk images, VirtioFS mounts, vsock, network
• Vm lifecycle: create, start, pause, resume, stop
• VirtioFS: shared directory configuration, read-only vs read-write
• Vsock: VsockStream (AsyncRead + AsyncWrite), VsockListener
• Save/restore VM state (macOS 14+)
• macOS installer: download IPSW, install to disk image
• Delegate implementation for VM state changes

Build the high-level abstraction and the binary that runs inside the VM.

• Guest agent binary (vz-guest-agent): listens on vsock, executes commands, streams output
• Guest agent bootstrap: launchd plist, auto-start on boot, VirtioFS auto-mount
• SandboxPool: pre-warm VMs (up to 2), manage lifecycle
• SandboxSession: acquire VM, mount project, execute commands, release
• Channel<Req, Resp>: typed request/response protocol over vsock with length-prefixed JSON frames
• Session cleanup: process termination, temp file removal between sessions

CLI binary for standalone use.

• vz init — Download IPSW, create golden disk image, install macOS, install dev tools
• vz run — Start VM with mounts, optional headless mode
• vz exec — Run a command inside a running VM via guest agent
• vz save / vz restore — Snapshot and restore VM state
• vz list — Show running VMs and their state
• vz stop — Graceful shutdown

• Pre-built golden images with common dev tools (Xcode CLI, Homebrew, Rust, Node, Python)
• CI integration guides (GitHub Actions on Apple Silicon runners)
• Integration examples: HQ kernel worker backend, Claude Code sandbox, generic agent harness
• OCI registry for distributing golden images

Phase 1: vz crate
    │
    ├──────────────────────┐
    ▼                      ▼
Phase 2: vz-sandbox    Phase 3: vz-cli
    │                      │
    └──────┬───────────────┘
           ▼
    Phase 4: Ecosystem

Phase 1 must complete before Phase 2 or Phase 3 can begin. Phase 2 and Phase 3 can proceed in parallel (vz-cli can use the vz crate directly for basic VM operations before vz-sandbox exists). Phase 4 depends on both Phase 2 and Phase 3.