> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Bespoke Labs Sandbox

> Use boxd from Bespoke Labs' sandbox library: one Python API over many sandbox providers, with each boxd sandbox a full VM.

![The Bespoke Labs logo mark and wordmark inside the boxd card.](https://mintcdn.com/azin/GUvqATY0IhPdUBtf/images/boxd-x-bespoke-labs.png?fit=max\&auto=format\&n=GUvqATY0IhPdUBtf\&q=85\&s=874844e2554983d561e7a29858fdd6ba)

[Bespoke Labs](https://bespokelabs.ai) builds RL environments and infrastructure for training agents. Its open-source [sandbox library](https://github.com/bespokelabsai/sandbox-router), `bespokelabs-sandbox`, is one Python API to create a sandbox, run code and commands, move files, and run CLI agents like Claude Code and Codex, on Docker, Daytona, E2B, Modal, and other providers.

boxd is one of those providers since version 0.4.0. Each sandbox is an isolated boxd machine, a full Ubuntu 24.04 VM with Docker, Python, Node and git, and switching to it from another provider is a change of the backend name.

## Set up

**1. Install the library with the boxd extra**

```bash theme={"theme":"github-dark"}
pip install 'bespokelabs-sandbox[boxd]'
```

**2. Create an API key**

```bash theme={"theme":"github-dark"}
boxd auth keys create bespoke --org <your-org>
export BOXD_API_KEY=bxd_...
```

Machines are created and billed in the key's organization. When the key can reach more than one organization, `BOXD_ORG` picks one.

**3. Run code in a machine**

```python theme={"theme":"github-dark"}
from bespokelabs.sandbox import Sandbox

with Sandbox("boxd", cpu=2, memory_mb=8192, timeout_secs=3600) as sb:
    print("machine:", sb.provider_resource_id)
    result = sb.execute_code("import platform; print(platform.platform())")
    print(result.stdout.strip())
    result = sb.execute_command("docker", ["--version"])
    print(result.stdout.strip())
```

```text theme={"theme":"github-dark"}
machine: <machine-id>
Linux-6.18.0+-x86_64-with-glibc2.39
Docker version 29.1.3, build 29.1.3-0ubuntu3~24.04.2
```

The run took 8 seconds, machine included. Leaving the `with` block deletes the machine.

## Limit the network

`network=` sets an [egress allowlist](https://docs.boxd.sh/guides/egress-allowlist.md) on the machine before your code runs:

```python theme={"theme":"github-dark"}
from bespokelabs.sandbox import NetworkPolicy, Sandbox

policy = NetworkPolicy(mode="allowlist", domains=("pypi.org",))
with Sandbox("boxd", network=policy, timeout_secs=3600) as sb:
    for url in ("https://pypi.org", "https://example.com"):
        result = sb.execute_command(
            "curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", "-m", "10", url]
        )
        print(url, result.stdout, result.exit_code)
```

```text theme={"theme":"github-dark"}
https://pypi.org 200 0
https://example.com 000 6
```

`mode="none"` blocks everything, and `sb.set_network()` changes the policy of a running sandbox.

## Serve a port

`expose_port()` gives a port in the machine a public [HTTPS URL](https://docs.boxd.sh/guides/https.md):

```python theme={"theme":"github-dark"}
import urllib.request

from bespokelabs.sandbox import Sandbox

with Sandbox("boxd", timeout_secs=3600) as sb:
    sb.write_file("/workspace/index.html", "hello from boxd\n")
    sb.execute_command(
        "bash", ["-c", "cd /workspace && setsid python3 -m http.server 8000 >/dev/null 2>&1 &"]
    )
    port = sb.expose_port(8000)
    print(port.url)
    print(urllib.request.urlopen(port.url, timeout=30).read().decode().strip())
```

```text theme={"theme":"github-dark"}
https://port-8000.sandbox-<id>.boxd.sh
hello from boxd
```

The URL is public, with no login in front of it. The first one on a machine waits for its TLS certificate, which takes about 20 seconds.

## Options

| Option | On boxd |
| - | - |
| `cpu`, `memory_mb` | Rounded up to the smallest [machine size](https://docs.boxd.sh/guides/resources.md#machine-sizes) that holds both: 1 vCPU/4 GiB, 2/8, 4/16 or 8/32. |
| `timeout_secs` | Sets a [delete-after](https://docs.boxd.sh/guides/delete-after.md) timer, so boxd deletes the machine at that time even if your process dies. Without it, the machine stays until it is deleted. |
| `snapshot_id` | Creates the machine from a boxd [snapshot](https://docs.boxd.sh/guides/snapshots.md). `sb.snapshot()` saves one, with memory and disk. |
| `network` | `public`, `none`, or `allowlist` with `domains`. |
| `env_vars`, `workdir`, `files` | `env_vars` and `workdir` apply to every command. Commands run as the `boxd` user, and `/workspace` exists and belongs to that user. |
| `backend_options` | Passed to the boxd SDK's `machines.create()`, such as `region` or `labels`, plus `name_prefix`, `ready_timeout_secs` and `auto_hibernate_timeout`. |

`image=`, `dockerfile=` and `gpu=` are refused: a machine boots boxd's Ubuntu image and has no GPU. Run your image with Docker inside the machine, or start from a snapshot.

## What each machine gets

* **Isolation, always:** every machine is [isolated](https://docs.boxd.sh/use-cases/sandboxes.md#cut-off-from-your-fleet-by-design), with no boxd credentials inside and no route to your other machines.
* **No standby mid-job:** auto-suspend is off, so a long job between commands is not paused.
* **Cleanup on failure:** if creating a sandbox fails after boxd made the machine, the library deletes it, and finds it by a label it set when it has no id yet.
* **A clean end:** leaving the `with` block, or `sb.destroy()`, deletes the machine. Snapshots outlive it, so delete them when you no longer need them.

## Read more

* [`bespokelabs-sandbox` on GitHub](https://github.com/bespokelabsai/sandbox-router): the SDK reference, the agent guide, and the control plane
* [Provider feature matrix](https://github.com/bespokelabsai/sandbox-router/blob/main/docs/BACKENDS.md#feature-support-matrix)
* [`bespokelabs-sandbox` on PyPI](https://pypi.org/project/bespokelabs-sandbox/)
* [Sandboxes on boxd](https://docs.boxd.sh/use-cases/sandboxes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.