The Problem
Developers using large‑language‑model agents (Claude Code, Codex, Amp) need isolated, reproducible environments that include the exact services, databases and secrets the code expects. Creating, tearing down and cleaning such sandboxes manually is error‑prone and costly.
What This Does
sbx automates the entire sandbox lifecycle.
- Core –
control/sbx_control/app.pyis the CLI entry point that reads a.sbx/recipe.yamland drives a state‑machine that creates, prepares, restarts, pauses, resumes and deletes a sandbox. - Runtime –
control/sbx_control/runtime/__main__.pylaunches an E2B‑Embed container (seevendor/e2b-embed/compose/), mounts the repository, injects secrets, starts the agent process and exposes an HTTPS preview. - Catalog –
catalog/*/packages expose shared services (Postgres, ClickHouse, Neon, PlanetScale, AWS) as reusable templates;catalog/_lib/sbx_provider.pyis the shared provider shim. - Agent connectors –
control/sbx_control/connectors/amp/__main__.pyand similar files stitch agent CLI commands into the sandbox template so that a session can be started from within the sandbox.
How It Is Wired
- Entry point –
control/sbx_control/app.pydefinesmain(). It parses CLI flags, loadssbx_control/template_filesand dispatches to subcommands such asup,down,preview. - Sandbox creation –
main()callssbx_control.runtime.manager.create_sandbox(recipe). runtime.managerreads the recipe, resolves catalog packages, writes a docker‑compose file incontrol/sbx_control/runtime/embed, and callsruntime.embed.__main__to start the container.- Secrets –
sbx_control/secret_store/__main__.pyreads.sbx/secrets.yamlor environment variables, injects them into the container via Docker secrets or environment variables. - Preview – After the container starts,
runtime.embed.__main__queries the agent’s HTTP endpoint, registers the preview URL with GitHub (if a PR preview is requested), and prints the link. - Cleanup –
runtime.manager.delete_sandboxremoves the container, deletes the local.sbx/statefiles and tears down any provisioned cloud resources via the catalog provider API.
The wiring is linear: CLI → runtime manager → runtime embed → Docker/E2B runtime. The widest blast radius is the runtime embed layer: changing its compose template would affect every sandbox. Catalog packages form small, isolated modules; swapping them only requires editing the .sbx/recipe.yaml.
How To Use It
Setup
# 1. Clone
git clone https://github.com/moses-y/sbx
cd sbx
# 2. Install core deps
pip install -r control/requirements.txt # or `uv pip install -e .`
# 3. Install web UI (optional)
cd web && npm ci
Configuration
- Server – the host that will run the Firecracker VMs; must have
/dev/kvmand Docker. - Secrets – place a
secrets.yamlin the repository root or in.sbx/. - Recipe – create a
.sbx/recipe.yamlin the repo root; seeexamples/for complete samples.
Running
# From the repo root
sbx up # starts a new sandbox
sbx preview # prints preview URLs
sbx down # cleans up
The CLI is documented in docs/agent-install.md.
Real‑World Use
A team uses Claude Code to edit a new microservice. The agent writes a .sbx/recipe.yaml that requests a Postgres instance and a ClickHouse backend. sbx up provisions the databases on a shared AWS RDS cluster, injects the connection strings into the sandbox, starts the service container, and publishes a preview link that the developer can visit in a browser. After testing, sbx down removes the databases and the VM, leaving no trace.
Code Health & Issues
- Low – 1 secret‑shaped path:
vendor/e2b-embed/compose/.env. The audit flags this file because it contains environment variables that may hold secrets; it is vendor code, so the risk is limited to the embedded runtime. No other findings were reported in the static analysis run.
The Bottom Line
sbx delivers a repeatable, per‑sandbox provisioning system that hides the plumbing behind a simple CLI. It is well‑structured: the core, runtime and catalog layers are clearly separated, making incremental changes straightforward. The main limitation is the modest test coverage; adding unit tests for the catalog providers would strengthen confidence. Teams that need to spin up isolated environments for LLM agents or CI previews will find sbx a useful addition to their toolchain.