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.py is the CLI entry point that reads a .sbx/recipe.yaml and drives a state‑machine that creates, prepares, restarts, pauses, resumes and deletes a sandbox.
  • Runtime – control/sbx_control/runtime/__main__.py launches an E2B‑Embed container (see vendor/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.py is the shared provider shim.
  • Agent connectors – control/sbx_control/connectors/amp/__main__.py and 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.py defines main(). It parses CLI flags, loads sbx_control/template_files and dispatches to subcommands such as up, down, preview.
  • Sandbox creation – main() calls sbx_control.runtime.manager.create_sandbox(recipe).
  • runtime.manager reads the recipe, resolves catalog packages, writes a docker‑compose file in control/sbx_control/runtime/embed, and calls runtime.embed.__main__ to start the container.
  • Secrets – sbx_control/secret_store/__main__.py reads .sbx/secrets.yaml or 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_sandbox removes the container, deletes the local .sbx/state files 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/kvm and Docker.
  • Secrets – place a secrets.yaml in the repository root or in .sbx/.
  • Recipe – create a .sbx/recipe.yaml in the repo root; see examples/ 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.