Platform

Run on your machine

smx runs sandboxes on the machine it runs on: one Firecracker microVM per sandbox, in process, with no daemon, no account and no login.

Requirements

  • Linux x86_64 with /dev/kvm. Sandboxes boot as your own user, without sudo.
  • Windows: WSL2 with nested virtualization.
  • macOS: planned.
  • For agents: a model the harness can reach, such as a local Ollama server.

Install

$ ./install.sh # make build && bin/smx install $ smx install --check # what is installed, what is missing $ smx doctor

smx install puts a pinned static firecracker and smx in ~/.local/bin, prepares the guest assets, then runs smx init. Flags after -- go to init, for example to grant a local model endpoint: smx install -- --model-endpoints <model-host>:tcp/11434. Details: Quickstart.

Create a sandbox and run commands

$ smx create --session dev -m 2G --disk 8G $ smx exec dev -- uname -a $ smx exec --timeout 30s -u 1000:1000 dev -- make test $ smx cp ./src dev:/workspace $ smx stop dev # keeps the workspace and the settings $ smx delete dev

Pause, snapshot, restore and commit are covered in the Quickstart. Network egress is set per sandbox with --security-profile; see Policies.

Run a coding agent

Create a sandbox that can reach only the model, mount a project directory, then start an agent in it. Every step is recorded in a run log, including each action a policy refused.

$ smx create --session s1 --image ghcr.io/semanticcodelab/semantic/opencode:latest \ --security-profile model-only --mount ~/proj:/work $ smx agent run s1 --harness opencode --cwd /work "Create sum.py that prints the sum of 1..100, run it" [state] provisioning → running [tool] edit: work/sum.py (completed) [file] write /work/sum.py 26B [tool] execute: python3 sum.py (completed) 5050 [state] finishing → succeeded (end_turn)

Harnesses: opencode, claude, codex, hermes or a plain shell. Agent runs are local by default; no account is needed.

Next