# 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

**Python**

```
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**

```
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](https://sandbox.wbx.cz/docs/templates.md). |
| `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](https://sandbox.wbx.cz/docs/sandboxes/sleep.md). |
| `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](https://sandbox.wbx.cz/docs/sandboxes/sleep.md). |
| `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](https://sandbox.wbx.cz/docs/templates.md) 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](https://sandbox.wbx.cz/docs/jobs/compute.md). Without `compute_class` your account's default class is used. |
| `dependency_cache` | `false` turns off the package cache for this sandbox – see [Package cache](https://sandbox.wbx.cz/docs/sandboxes/network.md#depcache). |
| `network` | `{"mode": "full"}` (default), `{"mode": "none"}`, or `{"mode": "allowlist", "allow": [...]}`; optional `"block": [...]` and `"ip"`: `ipv4` (default), `dual` or `ipv6`. See [Network and IPv6](https://sandbox.wbx.cz/docs/sandboxes/network.md). |

### 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](https://sandbox.wbx.cz/docs/jobs/receipts.md)); 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](https://sandbox.wbx.cz/docs/sandboxes/sleep.md). |
| GET /v1/sandboxes/{id}/url?port=8080 | sb.get_url(8080) | Public HTTPS URL of a port in the sandbox – see [Public URLs](https://sandbox.wbx.cz/docs/sandboxes/urls.md). |
| 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](https://sandbox.wbx.cz/docs/limits.md).

Source: https://sandbox.wbx.cz/docs/sandboxes
