A CLI tool that spins up a Linux sandbox VM on your machine for local development. Powered by QEMU and Ubuntu cloud images — no Docker, no VirtualBox, no cloud account required.
- macOS or Linux (Windows support is experimental)
- macOS or Linux: QEMU —
brew install qemu/sudo apt install qemu-system qemu-utils - Node.js 18+
sandboxctl ships an agent skill for Claude Code, Cursor, Codex, and other AI coding assistants. It analyzes your project and writes a sandbox.json for you — detecting runtimes, port requirements, and appropriate VM sizing automatically.
Install it with:
npx skills add inputforge/sandboxctlOnce installed, ask your assistant: "create a sandbox for this project" and it will run the full setup wizard inline.
Run in any project directory:
npx sandboxctlThis launches a setup wizard that checks prerequisites, walks you through configuration, and optionally boots the VM — all in one session.
Or install globally for day-to-day use:
npm install -g sandboxctl
sandboxctl # setup wizard
sandboxctl ssh # shell inside the VMsandboxctl <command>
Commands:
init Configure sandbox.json interactively
start Build (if needed) and boot the sandbox VM
stop Gracefully shut down the VM
destroy Delete the VM and all associated files
status Show sandbox name, status, SSH port, and uptime
ssh Open an interactive SSH session into the VM
send Sync project files from host → VM (uses rsync or tar)
receive Sync files from VM → host
forward [port] Forward a port: <guest-port> or <host-port>:<guest-port>
doctor Check that required dependencies are installed
Running sandboxctl with no arguments starts the setup wizard:
- Prerequisite check — verifies the required backend (Lima on macOS, QEMU on Linux) is installed and prints the install command if not
- Configuration — runs the
initprompts; ifsandbox.jsonalready exists all fields are pre-populated with current values so you can press Enter to keep them - Boot offer — asks whether to start the VM immediately after saving config
Checks that the required binaries are present for your platform and reports the install command for anything missing:
sandboxctl doctorOn first boot, the tool will:
- Download the Ubuntu cloud image (cached in
~/.local/share/sandboxctl/images/) - Create a QCOW2 overlay disk
- Build a cloud-init seed image with your SSH public key and install script
- Boot the VM in the background
- Stream the package install log until
==> Done. - Rsync your project files into the VM
Subsequent start calls skip provisioning and boot in seconds.
Generated by sandboxctl init (or the wizard). You can also write it by hand:
{
"ubuntu": "24.04",
"vm": {
"cpus": 4,
"memory": "4G",
"disk": "20G"
},
"packages": {
"nodejs": { "enabled": true, "version": "22" },
"bun": { "enabled": false },
"python": { "enabled": true },
"go": { "enabled": false }
},
"send": {
"remotePath": "/home/ubuntu/my-project"
},
"ports": [{ "host": 3000, "guest": 3000, "protocol": "tcp" }]
}| Package | Versioned | Default |
|---|---|---|
| Node.js | yes | 22 |
| Bun | yes | 1.3.12 |
| Python 3 | no | — |
| Java (OpenJDK) | yes | 21 |
| Go | yes | 1.24.3 |
| Ruby | no | — |
| PHP | no | — |
| Swift | yes | 6.0.3 |
ports is an optional array of host↔guest port mappings. Useful for accessing a dev server running inside the VM.
| Change | Action required |
|---|---|
ubuntu version | destroy + start |
packages | destroy + start |
vm.disk (grow only) | stop + start |
vm.cpus / vm.memory | stop + start |
ports / send.remotePath | stop + start |
send pushes your current directory to the VM (respects .gitignore). It uses rsync when available and falls back to tar over SSH.
sandboxctl send # host → VM
sandboxctl receive # VM → hostnpm install
npm run build # compile all packages (required before npm run cli)
npm run cli # run the compiled CLIMIT