Sandbox

Sandbox gives code a temporary machine without handing it the host. It is a self-hosted Rust control plane for disposable environments used by people, CI, and coding agents. The controller owns policy and lifecycle; workers execute approved work with bounded resources and explicit cleanup.

What it is—and is not

Sandbox is an execution control plane. One sandboxd binary can run as a controller, a worker, or both. The small sandbox CLI and sandbox-mcp local stdio bridge talk to the same authenticated API, so terminal scripts and agents use one lifecycle model.

It is not a claim that every container is a hardened tenant boundary. The built-in Docker runtime is for dedicated hosts or workloads within the same trust boundary. Mutually hostile workloads need a VMM-grade external runtime driver; if that capacity is unavailable, the controller should refuse the work instead of silently downgrading isolation.

The normal lifecycle

Every mutation is observable. A request becomes a typed sandbox spec; the controller authenticates it, applies policy and AEGIS placement, records an operation, assigns a capable worker, and eventually removes the environment.

Classify repository trust, generated code, network needs, secrets, and TTL.
Create the smallest suitable environment.
Wait for the lifecycle operation rather than assuming transport success.
Execute argv-safe commands with bounded output.
Delete the sandbox and any public route when the task ends.

1234567sandbox create --tenant platform --image ubuntu:24.04 \
  --cpu-millis 2000 --memory-mib 4096 --ttl 3600 \
  --network restricted --untrusted-repo --generated-code

sandbox wait OPERATION_ID --timeout 900
sandbox exec SANDBOX_ID -- cargo test --workspace
sandbox delete SANDBOX_ID --wait

Choose your path

You want to…	Read this next
Run the controller, a Docker worker, and PostgreSQL	Set up a server
Use an existing controller from a workstation or coding agent	Set up a client
Put the controller and tunnel URLs behind HTTPS	Set up custom domains
Create, execute, inspect, share, and delete environments	CLI workflows
Connect Codex, Claude Code, Gemini, Cursor, or another client	MCP and skills
Give an agent the small safe operating playbook	sandbox-platform skill
Choose isolation and public-exposure policy	Security and isolation

The pieces

The controller decides; the worker executes. The controller owns authentication, validation, AEGIS placement, durable desired state, leases, operations, and cleanup. A worker advertises capacity and isolation capability, runs one selected runtime adapter, bounds output, and returns a result.

PostgreSQL is the durable source of truth. NATS can publish lifecycle events, but events are best-effort and never replace state reconciliation. The complete model is in Sandbox architecture; production recovery and capacity guidance live in operations.

Get the code and installers

Start with the public source before trusting a deployment. The repository contains the controller, worker, CLI, MCP bridge, configuration, compose files, and the agent skill. The hosted installer adds the client pieces on supported machines.

1curl -fsSL https://tools.yshubham.com/sandbox/setup.sh | sh

Read the GitHub repository, the self-hosted forge mirror, or the machine-readable Sandbox document index when you need release-specific material.