Quick Start

Getting started in under a minute.

AgentRunBox gives your AI agents a secure sandbox to execute code, run commands, and manage files.

quickstart.ts
import { Sandbox } from "@agentrunbox/sdk"
// Create a sandbox
const sandbox = await Sandbox.create()
// Execute commands
const result = await sandbox.exec("echo 'Hello World'")
console.log(result.stdout) // "Hello World"
// Write and read files
await sandbox.writeFile("/work/data.txt", "hello")
const data = await sandbox.readFile("/work/data.txt")
// Clean up
await sandbox.destroy()

Installation

terminal
$ npm install @agentrunbox/sdk
# or
$ pnpm add @agentrunbox/sdk
Base URL: https://api.agentrunbox.com (production) or http://localhost:8787 (local dev).

Authentication

All API requests require a Bearer token in the Authorization header. Two types are supported:

API Keys

Prefixed with arb_. Created via the dashboard or API. Best for programmatic access.

Authorization: Bearer arb_sk_...

JWT Tokens

Issued via POST /auth/login. 7-day expiry. Best for session-based access.

Authorization: Bearer eyJhbG...

Providers

Choose the right isolation level for your use case.

In-Process local

Fastest. Runs in the same V8 isolate. Sub-1ms start. Works in Workers and browsers.

Docker docker

Full Linux environment. Any Docker image. Best for native toolchains.

Cloudflare cloudflare

Edge-deployed containers. Global distribution, auto-scaling.

Bare Metal bare

Your own infrastructure. Point at any host running the agent binary.

API Reference

Complete REST API. All endpoints accept and return JSON unless noted. Streaming endpoints use Server-Sent Events.

Base URL: https://api.agentrunbox.com

Sandboxes

Sandbox lifecycle — create, list, pause, resume, destroy.

POST /sandboxes

Create a new sandbox

Request Body 
{
  "template": "node",         // base|node|python|rust|go
  "metadata": { "user": "abc" },
  "envVars": { "NODE_ENV": "production" },
  "timeout": 600,             // seconds (30-3600)
  "files": {                  // seed files
    "/project/index.js": "console.log('hello')"
  }
}
Response 
{
  "id": "sbx_abc123def456",
  "status": "running",
  "template": "node",
  "metadata": { "user": "abc" },
  "createdAt": "2026-04-10T12:00:00Z",
  "expiresAt": "2026-04-10T12:10:00Z"
}
GET /sandboxes

List sandboxes

Query params: status (running|paused|stopped), metadata (key:value filter).

Response 
{ "sandboxes": [SandboxInfo, ...] }
GET /sandboxes/:id

Get sandbox details

Response 
SandboxInfo
DELETE /sandboxes/:id

Destroy sandbox

Cleans up R2 blocks, D1 metadata, and container.

Response 
{ "ok": true, "id": "sbx_..." }
POST /sandboxes/:id/pause

Pause sandbox

Sleeps container, keeps filesystem in R2. No compute charges.

Response 
{ "ok": true, "status": "paused" }
POST /sandboxes/:id/resume

Resume paused sandbox

Response 
{ "ok": true, "status": "running" }
POST /sandboxes/:id/keepalive

Extend idle timeout

Response 
{ "ok": true }

Commands

Command and bash script execution with hybrid routing.

POST /sandboxes/:id/commands

Run a command (one-shot)

Built-in commands (grep, find, awk, sed, etc.) run in-worker. Unknown commands auto-escalate to the container.

Request Body 
{
  "command": "grep",
  "args": ["-rn", "TODO", "/project/src"],
  "cwd": "/project",
  "timeout": 30000,
  "envVars": { "DEBUG": "1" }
}
Response 
{
  "stdout": "src/app.ts:42: // TODO fix\n",
  "stderr": "",
  "exitCode": 0,
  "durationMs": 2.3,
  "executedIn": "worker"   // worker|sandbox|mixed
}
POST /sandboxes/:id/commands/stream

Run command with SSE streaming

Same request body. Returns text/event-stream with events: stdout, stderr, exit, error.

Request Body 
{ "command": "npm", "args": ["test"] }
Response 
event: stdout
data: {"line": "PASS src/app.test.ts"}

event: exit
data: {"exitCode": 0, "durationMs": 2340, "executedIn": "sandbox"}
POST /sandboxes/:id/bash

Execute a bash script

Full bash with pipes, expansion, control flow. Shell state (env, cwd, functions) persists across calls.

Request Body 
{
  "script": "cd /project && npm install && npm test",
  "cwd": "/project",
  "timeout": 60000
}
Response 
{
  "stdout": "...",
  "stderr": "...",
  "exitCode": 0,
  "durationMs": 4200,
  "executedIn": "mixed"
}
POST /sandboxes/:id/bash/stream

Execute bash script with SSE streaming

Same as /bash but returns text/event-stream.

Files

Filesystem operations — read, write, search, bulk upload/download.

GET /sandboxes/:id/files?path=/dir

List directory contents

Response 
{
  "path": "/project/src",
  "entries": [
    { "name": "app.ts", "type": "file", "size": 1234 },
    { "name": "utils", "type": "directory" }
  ]
}
GET /sandboxes/:id/files/<path>

Read a file

Returns file content as text/plain. Headers: X-File-Path, X-File-Size.

Response 
(text/plain) file contents
PUT /sandboxes/:id/files/<path>

Write/create a file

Send file content as text/plain or application/octet-stream body.

Response 
{ "path": "/project/src/app.ts", "size": 1234 }
DELETE /sandboxes/:id/files/<path>

Delete file or directory

Response 
{ "ok": true, "path": "/project/old.txt" }
PATCH /sandboxes/:id/files/<path>

Move/rename a file

Request Body 
{ "destination": "/project/new-name.ts" }
Response 
{ "from": "/project/old.ts", "to": "/project/new-name.ts" }
POST /sandboxes/:id/files/upload

Bulk upload files

Request Body 
{
  "files": {
    "/project/src/a.js": "const x = 1;",
    "/project/src/b.js": "const y = 2;"
  }
}
Response 
{ "written": 2 }
POST /sandboxes/:id/files/download

Download multiple files

Request Body 
{ "paths": ["/project/a.js", "/project/b.js"] }
Response 
{ "files": { "/project/a.js": "...", "/project/b.js": "..." } }
POST /sandboxes/:id/files/search

Search file contents (grep-like)

Request Body 
{
  "pattern": "TODO|FIXME",
  "path": "/project",
  "glob": "**/*.ts",
  "maxResults": 100
}
Response 
{
  "matches": [
    { "file": "/project/src/app.ts", "line": 42, "content": "// TODO fix" }
  ]
}
POST /sandboxes/:id/files/find

Find files by glob pattern

Request Body 
{ "pattern": "**/*.ts", "path": "/project" }
Response 
{ "files": ["/project/src/app.ts", "/project/src/utils.ts"] }

Processes

Long-lived process management. Runs in the container.

POST /sandboxes/:id/processes

Start a long-lived process

Runs in the container sandbox. Returns immediately with a PID.

Request Body 
{
  "command": "npm",
  "args": ["run", "dev"],
  "cwd": "/project",
  "envVars": { "PORT": "3000" }
}
Response 
{
  "pid": "proc_xyz789",
  "command": "npm",
  "args": ["run", "dev"],
  "status": "running",
  "startedAt": "2026-04-10T12:00:00Z"
}
GET /sandboxes/:id/processes

List running processes

Response 
{ "processes": [ProcessInfo, ...] }
GET /sandboxes/:id/processes/:pid

Get process details

Response 
ProcessInfo
DELETE /sandboxes/:id/processes/:pid

Kill a process

Query param: force=1 for SIGKILL (default SIGTERM).

Response 
{ "ok": true, "pid": "proc_xyz789" }
GET /sandboxes/:id/processes/:pid/logs

Get process logs

Query param: since (cursor/timestamp).

Response 
{ "logs": ["line1", "line2", ...] }
GET /sandboxes/:id/processes/:pid/logs/stream

Stream process logs (SSE)

Returns text/event-stream with log lines.

POST /sandboxes/:id/processes/:pid/input

Send stdin to a process

Send text/plain body as stdin input.

Response 
{ "ok": true }

Git

Git operations via isomorphic-git. Runs in-worker.

POST /sandboxes/:id/git/clone

Clone a repository

Runs in-worker via isomorphic-git. Supports shallow clones.

Request Body 
{
  "url": "https://github.com/user/repo.git",
  "path": "/project",
  "branch": "main",
  "depth": 1
}
Response 
{
  "ok": true,
  "path": "/project",
  "url": "https://github.com/user/repo.git",
  "branch": "main"
}
GET /sandboxes/:id/git/status?path=/project

Git status

Response 
{
  "path": "/project",
  "files": [
    { "filepath": "src/app.ts", "status": "modified", "staged": false },
    { "filepath": "src/new.ts", "status": "new", "staged": false }
  ]
}
POST /sandboxes/:id/git/commit

Stage and commit changes

Request Body 
{
  "path": "/project",
  "message": "feat: add new feature",
  "files": ["src/app.ts"],
  "author": {
    "name": "agentrunbox",
    "email": "sandbox@agentrunbox.dev"
  }
}
Response 
{ "oid": "a1b2c3d...", "message": "feat: add new feature" }
GET /sandboxes/:id/git/log?path=/project&depth=20

Git log

Response 
{
  "path": "/project",
  "commits": [{
    "oid": "a1b2c3d...",
    "message": "feat: add new feature",
    "author": { "name": "agent", "email": "..." },
    "timestamp": 1712750400
  }]
}
GET /sandboxes/:id/git/diff?path=/project

Git diff (changed files)

Response 
{
  "path": "/project",
  "changes": [
    { "filepath": "src/app.ts", "status": "modified" }
  ]
}

Schemas

Core data types returned by the API.

SandboxInfo
Field Type
id string
status SandboxStatus
template string
metadata object
createdAt string (ISO 8601)
expiresAt string | null
CommandResponse
Field Type
stdout string
stderr string
exitCode integer
durationMs number
executedIn string
FileEntry
Field Type
name string
type string
size integer
modifiedAt string
ProcessInfo
Field Type
pid string
command string
args string[]
status string
startedAt string
exitCode integer