Docs

Quickstart

Install smx, boot a microVM sandbox, and run a coding agent inside it under a policy you control.

Requirements

Linux, x86_64, with /dev/kvm readable and writable by your user. No sudo needed to install.
mke2fs (e2fsprogs) and a static busybox (busybox-static).
slirp4netns for rootless networking.

Platforms: Linux x86_64 with KVM, and Windows via WSL2. Planned: macOS (Apple Silicon).

Install

From a checkout of the sandbox runtime:

$ ./install.sh # make build && bin/smx install $ smx doctor # check the install and the host settings

smx install puts a pinned static firecracker and smx in ~/.local/bin (--bin-dir), fetches the guest kernel, builds the initrd and runtime drive into ~/.scl/fc (--assets-dir), then runs smx init to record this host's settings. Re-running it is safe. Sandbox state lives in ~/.scl/sandbox.

smx install --check lists what is installed and what is missing without changing anything.

Create a sandbox and run a command

Each sandbox is a Firecracker microVM with its own kernel. There is no daemon: every smx command runs in process.

$ smx create --session dev -m 2G --disk 8G $ smx exec dev -- uname -a $ smx exec --timeout 30s -u 1000:1000 dev -- make test $ smx shell dev # interactive shell on a real terminal $ smx list

Useful create flags: --image REF (an OCI image), --security-profile NAME (egress), --env NAME=VALUE, -c FILE (a YAML sandbox config; flags override it).

Stop, pause, snapshot, restore

smx stop dev # keeps the root filesystem, /workspace and settings smx start dev # boots it again with the same settings smx pause dev # freeze in place: vCPUs stop, memory kept smx resume dev smx snapshot --session dev ghcr.io/me/warm:1 # disk + live memory as one OCI artifact smx restore --image ghcr.io/me/warm:1 --session next smx commit --session dev ghcr.io/me/dev:1 # root changes as an image layer, no memory smx delete dev # stop and remove everything

A restored sandbox continues mid-execution, with its processes and memory. pause writes nothing to disk; snapshot does, and the sandbox keeps running.

Copy files in and out

$ smx cp ./src dev:/workspace # host -> sandbox $ smx cp dev:/workspace/out.json . # sandbox -> host

Copying out writes only regular files and directories, never outside the destination; symlinks are skipped. To share a host directory live instead, mount it at create time:

$ smx create --session dev --fs-allow rw:~/app=/workspace/app --fs-deny ~/app/.env

Run an agent harness in a sandbox

smx agent run starts Claude Code, Codex, OpenCode or Hermes inside a sandbox you created and streams its events:

$ smx agent run dev --harness claude "fix the failing test" $ smx agent runs # list runs $ smx agent logs <run-id> -f # follow a run's events $ smx agent cancel <run-id>

--harness takes claude, codex, opencode, hermes or shell. The run uses the sandbox's security profile and filesystem policy; check what an agent may do with smx agent policy check dev --harness claude.

Managed beta: the hosted service is in private beta. Request access.

Policies

A policy says what an agent may touch. It lives outside the sandbox and the agent cannot change it.

area	set with	example
Files	--fs-allow / --fs-deny / --fs-default	--fs-allow ro:~/data --fs-deny ~/.ssh
Network	--security-profile, --allow, --deny	offline \| model-only \| internet \| internet-lan \| unrestricted
Change live	smx security-profile apply	smx security-profile apply offline dev
Git	smx vc policy	smx vc policy explain dev

Full syntax and examples: Policies. How enforcement works: Security model.

CLI reference

The main smx verbs. smx --help prints all of them with their flags.

command	what it does
install [--check]	Install firecracker, guest kernel, initrd and runtime drive, then run init; no sudo
init [--check]	Check this host and record its settings once
doctor	Check everything install and init set up; changes nothing
health [<name>] [--probe]	Process, ping, filesystem and network checks for one or every running sandbox
create [flags]	Boot a sandbox and leave it running
list [--json]	Sandboxes with state, pid and age
exec <name> -- <argv>	Run a process in a sandbox; exit code propagated
shell <name>	Interactive shell in the sandbox
cp <src> <dst>	Copy a file or directory to or from a sandbox (`name:/path`)
stop / start / restart <name>	Stop keeping the workspace; boot again with the same settings
pause / resume <name>	Suspend in place and continue
wait [--timeout D] <name>	Block until the sandbox has stopped
update <name> [flags]	Change CPU cap, memory, disk or network policy
snapshot --session ID REF	Push disk and live memory as one OCI artifact
restore --image REF --session ID	Bring a snapshot back mid-execution
commit --session ID REF	Push root changes as an OCI layer on its image
archive / unarchive	Move a stopped sandbox to a directory and bring it back
metrics [<name>] [--watch]	CPU, memory, disk and network use of running sandboxes
image pull \| ls \| inspect \| rm	Manage sealed base images on this host
agent run <name> --harness H	Start an agent run in a sandbox and stream its events
harness show \| set \| clear \| schema	A sandbox's stored harness parameters
security-profile list \| show \| create \| apply	Built-in and saved egress profiles
vc policy list \| show \| set \| explain	Saved git policies
net test \| policy \| probe	Verify network enforcement end to end
delete <name> [--force]	Stop and remove the sandbox and its workspace

Troubleshooting

Start with smx doctor. It reports each piece as ok, MISSING or note and says how to fix it.

kvm missing: the host has no /dev/kvm or your user cannot open it. Enable virtualization, or add your user to the group that owns /dev/kvm.
firecracker, kernel, initrd, runtime drive missing: run smx install again.
busybox missing: install busybox-static, or pass --no-busybox to smx install.
network: rootless networking needs slirp4netns. Check each egress profile from inside real sandboxes with smx net test.
userfaultfd note: sandboxes run, but restores boot from disk without memory. Grant your user read-write on /dev/userfaultfd, e.g. a udev rule KERNEL=="userfaultfd", GROUP="kvm", MODE="0660".
A sandbox misbehaves: smx health dev prints one ok/FAIL line per check.
"this host is run by semantic-sandbox-worker": another process holds this host's lock; use that tool, or a separate --runtime-dir.