WBX Sandbox
Sandboxes

Create and manage sandboxes

A sandbox is a small Linux virtual machine with its own disk, network and processes. You choose a template and a lifetime, use it, and destroy it – or let it fall asleep with its files for later.

Create a sandbox

from wbxsandbox import Sandbox

sb = Sandbox.create(
    template="base",
    timeout=600,                                   # lifetime in seconds
    env={"OPENAI_API_KEY": "sk-…"},
    metadata={"user": "alice", "chat": "42"},
    allow=["pypi.org", "files.pythonhosted.org"],  # only these destinations
    ip="dual",                                     # IPv4 and its own public IPv6
)
print(sb.id)
curl -s -X POST https://sandbox.wbx.cz/v1/sandboxes \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "template": "base",
    "timeout_s": 600,
    "env": {"OPENAI_API_KEY": "sk-…"},
    "metadata": {"user": "alice", "chat": "42"},
    "network": {"mode": "allowlist", "allow": ["pypi.org", "files.pythonhosted.org"], "ip": "dual"}
  }'

Request fields – POST /v1/sandboxes

FieldDescription
templateTemplate name (default base). See templates.
timeout_sLifetime in seconds. Capped by your plan's maximum.
nameOptional name (lowercase letters, digits, . _ -, up to 63 characters). If you already have a sandbox with this name, it is returned instead of a new one (200 and header X-WBX-Existing: 1; a sleeping one is woken up) – see Sleep and wake.
on_timeout, idle_timeout_s"kill" (default) destroys the sandbox when its lifetime ends. "pause" puts it to sleep instead – also after idle_timeout_s seconds without any request (default 600, 60–604800). See Sleep and wake.
envEnvironment variables for every command and process in the sandbox.
metadataYour own key–value labels (strings), returned with the sandbox.
vcpu, mem_mbSize of the sandbox. Templates stored as a snapshot – all standard templates – have a fixed size shown on the templates page; leave both out for them, a different value is a 400 error. Counted against your plan's vCPU and memory limits.
compute_class, optimize_forCompute class and server choice inside it – see Compute classes. Without compute_class your account's default class is used.
dependency_cachefalse turns off the package cache for this sandbox – see Package cache.
network{"mode": "full"} (default), {"mode": "none"}, or {"mode": "allowlist", "allow": [...]}; optional "block": [...] and "ip": ipv4 (default), dual or ipv6. See Network and IPv6.

The sandbox object

Response 201:

{
  "id": "sb_sand02_6f83783733841dee",
  "template": "base",
  "state": "running",
  "vcpu": 2,
  "mem_mb": 512,
  "created_at": "2026-11-07T17:25:03Z",
  "expires_at": "2026-11-07T17:35:03Z",
  "metadata": {"user": "alice", "chat": "42"},
  "network": "allowlist",
  "ip": "dual",
  "info": {"start_ms": 4, "warm": true, "ipv6": "2a04:fac7:7701:138f:400:a9ff:fefe:15", "ipv6_prefix": "2a04:fac7:7701:138f::/64"},
  "template_build": {"name": "base", "source_image": "python:3.12-slim", "image_digest": "sha256:05a9…4177",
                     "built_at": "2026-11-15T20:43:54Z", "spec_sha256": "5fca…5f19", "rootfs_sha256": "16f7…867a"}
}

ip is the sandbox's IP version (ipv4, dual or ipv6); info.ipv6 and info.ipv6_prefix are present only with IPv6. template_build identifies the exact build of the template the sandbox started from (the same block as in a job's execution receipt); templates built before 0.15.59 have no image_digest and rootfs_sha256 until they are rebuilt.

Manage a sandbox

EndpointPython SDKWhat it does
GET /v1/sandboxesSandbox.list()List your running, paused and sleeping sandboxes.
GET /v1/sandboxes/{id}Sandbox.connect(id)One sandbox – the SDK attaches to it, for example in the next turn of a conversation.
POST /v1/sandboxes/{id}/timeoutsb.set_timeout(600)Set the remaining lifetime: {"timeout_s": 600}.
POST /v1/sandboxes/{id}/pausesb.pause()Freeze it with its memory; not billed while paused.
POST /v1/sandboxes/{id}/resumesb.resume()Continue a paused sandbox, or wake up a sleeping one.
POST /v1/sandboxes/{id}/sleepsb.sleep()Put it to sleep: files are kept, running programs stop, not billed while asleep – see Sleep and wake.
GET /v1/sandboxes/{id}/url?port=8080sb.get_url(8080)Public HTTPS URL of a port in the sandbox – see Public URLs.
GET /v1/sandboxes/{id}/metricsCPU, memory and disk usage inside the sandbox.
DELETE /v1/sandboxes/{id}sb.kill()Destroy it – disk and memory are discarded. Leaving a with block does this in Python.
GET /v1/templatesTemplates you can use.

Lifetime and billing

  • Every sandbox has a lifetime you choose when creating it (5 minutes by default in the Python SDK). When it runs out, the sandbox is destroyed – or, with on_timeout: "pause", it falls asleep. You can extend the lifetime at any time; the maximum depends on your plan.
  • You pay per second for vCPU and memory while a sandbox runs. A paused, sleeping or destroyed sandbox costs no compute.
  • How many sandboxes you can run at once and their size depend on your plan – see Limits.