By name: sandbox-guide
description: Guide for using the E2B-compatible local sandbox with Docker or Shuru microVMs
user-invocable: true
argument-hint: ""
Sandbox
E2B-compatible sandbox that runs locally using Docker or Shuru microVMs. Use the standard E2B SDK — when ready for production, switch to real E2B by changing one config value.
Quick Start
# Install
npm install -g @circlesac/sandbox
# Start (auto-generates API key on first run)
sandbox serve # starts the control plane on :49982
Architecture
E2B SDK → Control Plane (Hono on :49982) → Backend → Sandboxes (envd)
Backends:
- Docker (default): Linux containers via Docker Engine
- Shuru (macOS): Linux microVMs via Apple Virtualization.framework
The control plane proxies E2B SDK requests to sandbox instances running envd. Three routing layers:
- Host header —
{port}-{sandboxId}.{domain}for domain-based routing - E2b-Sandbox-Id header — gRPC transport (commands, process)
- X-Access-Token header — envd REST API (files, health)
Using with E2B SDK
import { Sandbox } from "e2b";
const sandbox = await Sandbox.create("base", {
apiUrl: "http://localhost:49982",
apiKey: "your-api-key", // from ~/.sandbox/config.json
sandboxUrl: "http://localhost:49982",
});
// Run commands
const result = await sandbox.commands.run("echo hello");
console.log(result.stdout); // "hello\n"
// File operations
await sandbox.files.write("/tmp/test.txt", "content");
const content = await sandbox.files.read("/tmp/test.txt");
// List directory
const entries = await sandbox.files.list("/tmp");
// Cleanup
await sandbox.kill();
CLI Commands
| Command | Description |
|---|---|
sandbox serve |
Start the control plane server (auto-generates API key on first run) |
sandbox status |
Show health, backend, and running sandbox count |
Backend Configuration
Edit ~/.sandbox/config.json to set the backend:
{
"apiKey": "sk-sandbox-...",
"backend": "shuru"
}
Omit backend or set to "docker" for Docker (default).
API Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /sandboxes |
Create a sandbox |
| GET | /sandboxes |
List sandboxes |
| GET | /sandboxes/:id |
Get sandbox info |
| DELETE | /sandboxes/:id |
Kill a sandbox |
| POST | /sandboxes/:id/timeout |
Update timeout |
| POST | /sandboxes/:id/pause |
Pause a sandbox (Docker only) |
| POST | /sandboxes/:id/resume |
Resume a paused sandbox (Docker only) |
| GET | /health |
Health check (no auth) |
All endpoints except /health require X-API-Key header.
Template Images
Docker
Templates map to Docker images. Resolution order:
- Local image:
sandbox-{templateId}:latest(e.g.,sandbox-base:latest) - GHCR fallback:
ghcr.io/circlesac/sandbox-{templateId}:latest
Build the base image: docker build -t sandbox-base:latest docker/sandbox
Shuru
Templates map to shuru checkpoints named sandbox-{templateId} (e.g., sandbox-base).
Create a checkpoint:
shuru checkpoint create sandbox-base --allow-net -- sh -c \
'apk add --no-cache bash sudo curl wget && ...'
If no sandbox-base checkpoint exists, shuru runs a plain Alpine VM.