sandboxesL3 runtime

A microVM per task, next to the model.

Each sandbox is a Firecracker microVM restored from a snapshot of its template. Run commands, stream output, read and write files, open a terminal and share a port. Code inside a sandbox reaches every B3OS product at 127.0.0.1:7700 with no network hop, and only with the scopes you grant it.

Get API key Read the docs

API: /v1/sandboxes
CLI: b3os sandbox create · b3os sandbox exec · b3os sandbox shell
MCP tools: sandbox_*

[01/03] What it does

Templates

base (Ubuntu 24.04, Python 3.12, Node 24, git), code-interpreter (a Jupyter kernel behind run_code) and agent (Claude Agent SDK, OpenAI Agents SDK and LangGraph installed).

GET /v1/sandboxes/templates

Exec

Buffered, streamed as server-sent events, or in the background with logs you can follow.

POST /v1/sandboxes/{id}/exec

Files and a terminal

Read and write files by path, list directories, and attach a terminal over WebSocket.

/files · /pty

Port previews

Expose a port at usercontent.b3os.org/sbx/…. Ports are private by default and shared through expiring, signed URLs.

POST /v1/sandboxes/{id}/ports/{port}/url

Pause, resume, snapshot

Pause an idle sandbox instead of stopping it, and start new sandboxes from a snapshot of a running one.

/pause · /resume · /snapshot

Scoped API access

The api grant decides what code in the sandbox may call. It never exceeds the scopes or spend cap of the key that created the sandbox, and it ends with the sandbox.

api: {scopes, spend_cap_usd}

What happens before your first exec

Template
base, code-interpreter or agent, booted once and snapshotted.
Warm slot
Restored, warmed with one exec, paused and parked before anyone asks.
Claim
Fresh entropy and identity are bound to your sandbox, then it resumes.
Exec
Commands run through the guest agent's pre-forked process over vsock.

1SBX=$(curl -sS https://beta-api.b3os.org/v1/sandboxes \
2  -H "Authorization: Bearer $B3OS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"template":"base","timeout_s":900}' | jq -r .id)
5
6curl -sS https://beta-api.b3os.org/v1/sandboxes/$SBX/exec \
7  -H "Authorization: Bearer $B3OS_API_KEY" \
8  -H "Content-Type: application/json" \
9  -d '{"cmd":["python3","-c","print(2 + 2)"]}'

SBX=$(curl -sS https://beta-api.b3os.org/v1/sandboxes \
  -H "Authorization: Bearer $B3OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"base","timeout_s":900}' | jq -r .id)

curl -sS https://beta-api.b3os.org/v1/sandboxes/$SBX/exec \
  -H "Authorization: Bearer $B3OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd":["python3","-c","print(2 + 2)"]}'

1const api = "https://beta-api.b3os.org/v1";
2const headers = {
3  Authorization: `Bearer ${process.env.B3OS_API_KEY}`,
4  "Content-Type": "application/json",
5};
6
7const sandbox = await fetch(`${api}/sandboxes`, {
8  method: "POST",
9  headers,
10  body: JSON.stringify({ template: "base", timeout_s: 900 }),
11}).then((r) => r.json());
12
13const run = await fetch(`${api}/sandboxes/${sandbox.id}/exec`, {
14  method: "POST",
15  headers,
16  body: JSON.stringify({ cmd: ["python3", "-c", "print(2 + 2)"] }),
17}).then((r) => r.json());
18console.log(run.stdout);

const api = "https://beta-api.b3os.org/v1";
const headers = {
  Authorization: `Bearer ${process.env.B3OS_API_KEY}`,
  "Content-Type": "application/json",
};

const sandbox = await fetch(`${api}/sandboxes`, {
  method: "POST",
  headers,
  body: JSON.stringify({ template: "base", timeout_s: 900 }),
}).then((r) => r.json());

const run = await fetch(`${api}/sandboxes/${sandbox.id}/exec`, {
  method: "POST",
  headers,
  body: JSON.stringify({ cmd: ["python3", "-c", "print(2 + 2)"] }),
}).then((r) => r.json());
console.log(run.stdout);

1import os
2
3import httpx
4
5api = httpx.Client(
6    base_url="https://beta-api.b3os.org/v1",
7    headers={"Authorization": f"Bearer {os.environ['B3OS_API_KEY']}"},
8    timeout=65,
9)
10
11sandbox = api.post("/sandboxes", json={"template": "base", "timeout_s": 900}).json()
12run = api.post(
13    f"/sandboxes/{sandbox['id']}/exec",
14    json={"cmd": ["python3", "-c", "print(2 + 2)"]},
15).json()
16print(run["stdout"])

import os

import httpx

api = httpx.Client(
    base_url="https://beta-api.b3os.org/v1",
    headers={"Authorization": f"Bearer {os.environ['B3OS_API_KEY']}"},
    timeout=65,
)

sandbox = api.post("/sandboxes", json={"template": "base", "timeout_s": 900}).json()
run = api.post(
    f"/sandboxes/{sandbox['id']}/exec",
    json={"cmd": ["python3", "-c", "print(2 + 2)"]},
).json()
print(run["stdout"])

1{
2  "name": "sandbox_exec",
3  "arguments": {
4    "sandbox_id": "sbx_01m5t68q1b590rj801nbzsqzkk",
5    "cmd": ["python3", "-c", "print(2 + 2)"]
6  }
7}

{
  "name": "sandbox_exec",
  "arguments": {
    "sandbox_id": "sbx_01m5t68q1b590rj801nbzsqzkk",
    "cmd": ["python3", "-c", "print(2 + 2)"]
  }
}

Guests have no network interface. Outbound traffic goes through the egress guard over vsock: public internet only by default, with deny and allowlist modes.
Each restore gets fresh entropy, a new machine id and a reseeded PRNG before it runs.

[02/03] Measured

What we measure for sandboxes

Values appear here only from published benchmark runs, each with its raw data. A row that says measuring has no published run yet.

Claim to first exec

Create a sandbox and run its first command, end to end on the same host, at idle. Pool depth stated.

Measuringp50, client side

Claim to first exec, 100 at once

The same under a burst of 100 simultaneous claims.

Measuringp50, client side

Exec round trip

Run /bin/true in a running sandbox: b3osd to the guest agent, process spawn, exit status back.

Measuringp50, server side

Pause and resume

Each of pause and resume on a running sandbox.

Measuringp50, server side

Fork

One fork of a sandbox with up to 128 MiB of RAM and 64 MiB dirty. Larger sizes are published as a curve.

Measuringp50, server side

Time to interactive, ComputeSDK harness

Create a sandbox and run node -v, measured by ComputeSDK's own harness from their runners: the shape other sandbox providers are measured in.

Measuringp50, client side

How we measure, and what others publish

[03/03] Beta limits

Free during the beta, with caps

Caps per organization

Sandboxes running at once: 10
vCPUs per sandbox: 2 vCPU
Memory per sandbox: 2 GiB
Sandbox lifetime: 1 h

Metered units

Sandbox CPU: sandboxes.vcpu_ms
Sandbox memory: sandboxes.gib_ms

Pricing details