sbx

README

sbx

Self-hosted sandboxes for AI agents. sbx gives every agent, test run or branch its own sandbox on your machine or cluster: a fresh Firecracker microVM with its own kernel, or a container. Idle sandboxes sleep at 0 B of RAM and wake the moment anything connects.

Agents drive it through the OpenSandbox API, an open standard with SDKs in five languages, or as tools over MCP. Anything else only has to connect: point psql, Playwright or a test runner at a sleeping sandbox and sbx holds the connection while it wakes, then hands it over.

• A microVM per sandbox on Linux with KVM, or a container anywhere Docker runs
• Written in Go with only the standard library: one static binary, zero dependencies
• No account and nothing hosted: MIT licensed, on your own hardware

Not to be confused with Docker's own sbx CLI (docker/tap/sbx).

Install

brew install aryanmehrotra/tap/sbx

Or curl -fsSL https://raw.githubusercontent.com/aryanmehrotra/sbx/main/scripts/install.sh | sh, or go install github.com/aryanmehrotra/sbx@latest. It needs Docker or a Kubernetes cluster, and Linux with /dev/kvm for microVMs. Run sbx doctor to see what your machine supports, and sbx install to add what it reports missing (it shows every command and asks first).

Sandboxes for AI agents

# The daemon, serving the OpenSandbox API with four sandboxes started ahead of time
sbx serve --osb-addr 127.0.0.1:8080 --osb-pool python:3.11-slim=4 &
export OPEN_SANDBOX_DOMAIN=127.0.0.1:8080 OPEN_SANDBOX_API_KEY="$(cat ~/.sbx/osb/key)"
pip install opensandbox

from opensandbox import SandboxSync

sandbox = SandboxSync.create("python:3.11-slim")
print(sandbox.commands.run("python -c 'print(6 * 7)'").logs.stdout[0].text)  # 42
sandbox.destroy()

Add --provider firecracker to sbx serve and every sandbox is a microVM with its own kernel, booted fresh from the image. To give Claude Code sandboxes as tools, run claude mcp add sbx -- sbx mcp while the daemon runs. Cursor and Codex are in GUIDES.md.

Databases for branches and tests

sbx serve --idle 5m &                               # once per machine
sbx create my-branch --template postgres            # a Postgres for this branch
eval "$(sbx env my-branch)"
PGPASSWORD=app psql -U app -d app                   # connecting wakes it

sbx snapshot my-branch seeded && sbx fork seeded agent-1         # seed once, copy per agent
sbx with test-db --template postgres -- go test ./...            # removed even if tests fail

Templates: postgres, browser, nginx, web-stack (Postgres and Redis) and analytics. For your own stack, write a sandbox.json (SPEC.md).

Documentation

• Quickstart: a first sandbox in ten minutes
• Guides: branches, CI, previews, AI agents
• Self-hosting: run it on your own servers for a team
• CLI reference and sandbox.json reference
• FAQ: what people ask before they adopt it
• Troubleshooting
• How it works, including where it has been tested
• Benchmarks and comparison with other tools
• Roadmap and release notes
• Security

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md; coding agents should read AGENTS.md.

License

MIT

Documentation

Overview

Command sbx gives every branch, task or agent its own copy of a project's backing services, and charges nothing for the ones nobody is using. The program lives in internal/app; this root file is only the entry point and the one thing that has to be here.