Sandboxes

A sandbox is a Firecracker microVM with its own kernel, claimed from a pool of microVMs that were restored from a snapshot ahead of time. Your request does not wait for a boot. Use one to run code an agent wrote, to give an agent a computer of its own, or to run the agent itself on the node, next to the model the node serves.

Create a sandbox

bash
curl -s https://beta-api.b3os.org/v1/sandboxes \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{"template": "base", "vcpu": 2, "memory_mib": 2048, "timeout_s": 900}'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const sandbox = await b3os.sandboxes.createSandbox({ template: "base", vcpu: 2, memory_mib: 2048, timeout_s: 900 });console.log(sandbox.id, sandbox.status, sandbox.expires_at);

python
from b3os import B3OSb3os = B3OS()sandbox = b3os.sandboxes.create_sandbox({"template": "base", "vcpu": 2, "memory_mib": 2048, "timeout_s": 900})print(sandbox["id"], sandbox["status"], sandbox["expires_at"])

text
Start a sandbox and run `python3 -c "import sys; print(sys.version)"` in it.

The sandbox comes back running. Its timing shows the claim.

Templates

GET /v1/sandboxes/templates lists the templates with their contents and default sizes:

Lifecycle

mermaid
stateDiagram-v2
  [*] --> running: create
  running --> paused: pause
  paused --> running: resume
  running --> stopped: delete or timeout
  paused --> stopped: delete or timeout
  running --> failed: microVM crashed

• Extend with POST /v1/sandboxes/{sandbox_id}/timeout and a new timeout_s, counted from now. It works on running and paused sandboxes.
• Pause freezes the vCPUs and keeps memory and disk on the node; resume continues exactly where it stopped, with the guest clock corrected. See snapshots and pausing.
• Delete stops the sandbox and destroys its memory and disk. It returns the stopped sandbox with its final usage; snapshots taken from it are kept.
• A stopped sandbox cannot be restarted. Calls that need a running one fail with sandbox_not_running, whose current_status says why.

Each sandbox starts with a fresh identity (new entropy, machine ID and clock), even when many come from one snapshot, so no two sandboxes share random state.

Networking

A sandbox has no network card. Its outbound traffic leaves through the node's egress guard, which allows the public internet by default and never the node's network, loopback or cloud metadata addresses. Narrow it per sandbox:

json
{ "template": "base", "egress": { "mode": "allowlist", "allow": ["github.com", "*.githubusercontent.com"] } }

deny blocks outbound traffic entirely. Inbound traffic reaches a sandbox only through its declared ports.

Inside the sandbox

The environment includes:

The B3OS SDK and CLI detect B3OS_API_URL and use it on their own.

Billing and scopes

A running sandbox bills sandboxes.vcpu_ms (CPU time it used) and sandboxes.gib_ms (allocated memory times wall time). A paused sandbox bills no CPU time. Whether it bills memory while paused is still being settled for the beta; the sandbox's usage shows what it was charged.

Guides

Limits and FAQ lists the caps and the common questions.