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
| Field | Description |
|---|---|
template | Template name (default base). See templates. |
timeout_s | Lifetime in seconds. Capped by your plan's maximum. |
name | Optional 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. |
env | Environment variables for every command and process in the sandbox. |
metadata | Your own key–value labels (strings), returned with the sandbox. |
vcpu, mem_mb | Size 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_for | Compute class and server choice inside it – see Compute classes. Without compute_class your account's default class is used. |
dependency_cache | false 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
| Endpoint | Python SDK | What it does |
|---|---|---|
| GET /v1/sandboxes | Sandbox.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}/timeout | sb.set_timeout(600) | Set the remaining lifetime: {"timeout_s": 600}. |
| POST /v1/sandboxes/{id}/pause | sb.pause() | Freeze it with its memory; not billed while paused. |
| POST /v1/sandboxes/{id}/resume | sb.resume() | Continue a paused sandbox, or wake up a sleeping one. |
| POST /v1/sandboxes/{id}/sleep | sb.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=8080 | sb.get_url(8080) | Public HTTPS URL of a port in the sandbox – see Public URLs. |
| GET /v1/sandboxes/{id}/metrics | CPU, 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/templates | Templates 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.