Sandboxes

A sandbox is a live Cloud Hypervisor microVM — isolated kernel, memory, and disk — driven by a single Go core.

nexus boots, pauses, snapshots, forks, and removes sandboxes. The CLI and MCP server are thin surfaces over the same library core. The governing principle is primitives, not workflow verbs.

nexus create my-app --image nexus-base
nexus exec my-app -- go test ./...
nexus exec my-app
nexus stop my-app

partial — current implementation uses nexus sandbox create; see CLI sandbox commands for the mapping.

Pages in this section

Page	What it covers
Sandbox model	The Sandbox entity — the one durable type in nexus
Lifecycle states	The five states, every legal transition, and what is explicitly illegal
Execution substrate	Cloud Hypervisor, the driver seam, vsock, and the network hook
Guest agent	The in-guest PID-1 agent: control plane, data plane, session reattach
Snapshots and fork	The Snapshot artifact, fork fan-out, cost table
Images	How a rootfs is built — Containerfile contract, builder VM, shipped images

Architecture overview

Design decisions

• One entity. Sandbox is the only durable type. There is no separate VM, Project, or Workspace entity.
• No transient states. An operation in flight holds a lease alongside the record; the record never enters an intermediate state.
• Custom agent, not a container runtime. The agent is a thin Go binary baked into every image. It speaks a narrow bespoke gRPC protocol; it does not implement OCI or any container spec.
• Zero VMM code. nexus drives Cloud Hypervisor over its REST API. It owns no hypervisor code.
• Live mounts as source. --mount <host-path>:<guest-path> mounts a host git worktree directory into the sandbox via virtiofs — bidirectional and live; edits inside appear on the host immediately. Fork and snapshot are refused on a live-mounted sandbox; N-way parallelism uses independent create calls, each with its own worktree.

What sandboxes can do

Build and test. Full Linux guests with unrestricted shell access. Large Go codebases build and test in-sandbox: go build ./... runs clean (CGO_ENABLED=0; no C compiler in the guest by default), with cold full-build around 32 seconds and per-package incremental test runs around 2 seconds.

Source init. Under the live-mount model, a host git worktree directory is mounted directly via virtiofs using --mount — edits inside appear on the host immediately, and fork/snapshot are refused on a live-mounted sandbox (see Snapshots and fork).

Nested virtualisation. /dev/kvm is absent inside a guest unless explicitly opted in at sandbox create time (--nested). Workloads that boot or manage VMs require it.

Egress control. Each sandbox runs under a default-deny egress perimeter — a per-sandbox hostname allowlist with L7 TLS MITM for credential injection, enforced by a detached supervisor that survives CLI exit.

Library composition

nexus ships a thin custom guest agent (no OSS init provided exec/PTY/snapshot-reattach composable with an external microVM substrate) and offloads everything else:

Concern	Library
VM execution (Linux)	Cloud Hypervisor
macOS VM execution	Virtualization.framework via nexus-vzd backlogged
Guest networking / egress	gvproxy
L7 MITM / TLS	goproxy + clawk CA
Image build	BuildKit
MCP surface	modelcontextprotocol/go-sdk

Integration seams

The driver seam owns the vsock transport primitive DialGuest and a network-hook primitive, and owns no protocol. agent and perimeter are peers of driver, not nested inside it. Surfaces (internal/cli, internal/mcp, out-of-tree plugins) are thin adapters over service with no surface-to-core RPC.