Skip to content

Sandboxes

A sandbox is a long-lived Firecracker microVM the daemon manages on your behalf. The same VM stays up across multiple run / browser.* / files.* calls — that's the whole point. Filesystem state, running processes, browser cookies all persist between calls.

Lifecycle

stateDiagram-v2
    [*] --> Provisioning: Sandbox.create()
    Provisioning --> Running: agent.py up on :8500
    Provisioning --> [*]: spawn failed
    Running --> Running: run / files / browser / process
    Running --> [*]: close() OR ttl expires OR proc dies

Every interaction touches the sandbox and resets the inactivity timer. After ttl_seconds of silence the daemon's reaper kills the VM and cleans up: tap device, IP allocation, rootfs overlay, profile cache.

Creating

from firebox.sandbox import Sandbox

sb = Sandbox.create(
    template="browser-use",   # rootfs image; default = base Ubuntu
    ttl_seconds=600,          # idle timeout in seconds
    vcpu=2,                   # CPUs visible to the guest
    mem_mib=2048,             # RAM
)
print(sb.id, sb.ip)           # "9d3a7e", "10.42.0.4"

Use it as a context manager whenever you can — guarantees close() even on exception:

with Sandbox.create(template="browser-use") as sb:
    sb.run("...")
# sb is closed here, regardless of whether the body raised

To rejoin an existing sandbox by ID:

sb = Sandbox.attach("9d3a7e")

Activity resets TTL

Every call below counts as activity:

Call Notes
sb.run(cmd) Synchronous shell exec
sb.stream(cmd) NDJSON-streamed stdout/stderr
sb.files.{read,write,upload,download,list} File ops
sb.process.{start,list} Background process ops
sb.browser.* Anything in the browser API
sb.http.* curl_cffi raw HTTP
sb.search.* SearxNG queries
sb.audio.transcribe Whisper transcription
sb.captcha.* Captcha solving

Whatever the largest TTL is when activity arrives, that's the new deadline.

TTL and quotas

  • Caller-side ceiling: pass ttl_seconds= at create time. No upper limit in the SDK itself.
  • Server-side ceiling: per-token max_ttl_seconds (see Tokens & quotas). The daemon clamps creates above this with HTTP 429.

Practical rule: long-running agent flows (browser-use style) → 300 – 1800 s. Short batch jobs → 60 s and rely on the reaper to clean up.

Ownership and visibility

Each sandbox records the token id that created it. Non-admin tokens:

  • can only run / close / drive sandboxes they own
  • only see their own sandboxes in firebox sandbox list
  • get HTTP 403 if they try to touch someone else's

Admin tokens see + control everything. Use firebox token list to inspect what's where.

Cleanup

The daemon reaps a sandbox when:

  1. The client calls sb.close() (or firebox sandbox close <id>)
  2. The TTL expires without activity
  3. The Firecracker process dies on its own (kernel panic, OOM, etc.)

Cleanup tasks (always atomic, even after crashes):

  • send /close to in-VM agent (best-effort flush)
  • SIGTERM the Firecracker process, escalate to SIGKILL after 5 s
  • delete tap-<id> from fbr0
  • free the IP allocation lock (/srv/firebox/ips/<N>/)
  • remove the rootfs overlay (/srv/firebox/vms/vm-<id>.ext4)
  • remove per-VM Firecracker config

Nothing else lingers. You can spawn the next sandbox immediately.