How It Works

From API call to result. In milliseconds.

AgentRunBox gives your AI agent an isolated environment to execute code. Here's what happens under the hood — from sandbox creation to command execution to cleanup.

Step 01

Create a Sandbox

A single POST request creates an isolated sandbox. Choose a template (base, node, python, rust, go), set environment variables, configure timeout, and optionally seed files.

Under the hood: a row is inserted into D1, a Durable Object is instantiated, and a Vm is lazily initialized on first use. The sandbox ID follows the format sbx_*.

create-sandbox.ts
import { Sandbox } from "@agentrunbox/sdk"
// Create with options
const sandbox = await Sandbox.create({
template: "node",
timeout: 600,
envVars: { NODE_ENV: "production" },
files: {
"/work/index.js": "console.log('ready')"
}
})
// sandbox.id → "sbx_a1b2c3d4e5f6"
// sandbox.status → "running"
Step 02

Execute Commands

Run individual commands or full bash scripts. The hybrid engine automatically routes each command to the fastest execution path — worker for built-ins, container for binaries.

Responses include stdout, stderr, exit code, execution duration, and where the command ran (worker, sandbox, or mixed for bash scripts that use both).

execute.ts
// Single command — runs in worker (<1ms)
const grep = await sandbox.exec("grep -rn TODO /work/src")
// Container command — escalated automatically
const node = await sandbox.exec("node /work/index.js")
// Full bash script — mixed execution
const result = await sandbox.bash(`
cd /work
npm install
npm test 2>&1 | grep FAIL
`)
// result.executedIn → "mixed"
// result.durationMs → 2340
Under the Hood

The command router.

Every command passes through the router. Built-in POSIX commands stay in the worker for sub-millisecond execution. Unknown binaries are transparently escalated to the container.

API REQUEST COMMAND ROUTER grep? awk? → WORKER node? python? → CONTAINER BUILT-IN ESCALATE V8 WORKER grep sed awk find xargs cat sort wc git diff ... <1ms CONTAINER node python cargo go npm pip any binary ~2s JSON RESPONSE
Step 03

Manage Files & Git

Read, write, search, and organize files through the REST API. Clone repositories, check status, stage changes, and commit — all without shelling out to git.

Bulk operations let you upload or download multiple files in a single request. File search supports regex patterns with glob filtering. Git operations use isomorphic-git running directly in the worker.

files-and-git.ts
// Write files
await sandbox.writeFile("/work/app.ts", code)
// Search across files
const hits = await sandbox.search("TODO|FIXME", "**/*.ts")
// Clone a repo
await sandbox.git.clone("https://github.com/user/repo")
// Check status, commit changes
const status = await sandbox.git.status("/work")
await sandbox.git.commit({
message: "feat: agent changes",
files: ["src/app.ts"]
})
Lifecycle

Pause, resume, destroy. Automatic cleanup.

Sandboxes can be paused to save costs (filesystem persists in R2), resumed when needed, and destroyed when done. Idle timeouts auto-pause after configurable inactivity.

CREATE POST /sandboxes RUNNING exec / files / git PAUSED R2 persisted RESUME DESTROY cleanup R2+D1 GONE IDLE TIMEOUT

Running

Active sandbox. Vm is initialized, commands execute, files are read/written. Metered usage.

Paused

Container stopped, Vm released. Filesystem persists in R2. No compute charges. Resume in <50ms.

Destroyed

Everything cleaned up. R2 blocks deleted, D1 metadata removed. No lingering state or cost.

Authentication

JWT + API Keys. Plan enforcement.

Two authentication methods. JWT tokens for sessions (7-day expiry). API keys (arb_* prefix) for programmatic access. Plans enforce limits on sandbox count, commands per day, storage, and timeout.

// Authenticate
const client = new AgentRunBox({
apiKey: "arb_sk_..."
})
// Or use JWT
const token = await auth.login(
"user@example.com",
"password"
)

Try it yourself.

Create your first sandbox in under a minute.

Start Free Documentation