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

# Run Novita Sandbox with Bespoke Labs sandbox-router

> Use Sandbox Router's Novita backend to execute Python and shell commands, transfer files, and reconnect to Novita Code Interpreter sandboxes.

[sandbox-router](https://github.com/bespokelabsai/sandbox-router) is an open-source Python library from [Bespoke Labs](https://bespokelabs.ai/) that gives you one API to run code, shell commands, file transfers and coding agents across sandbox providers. Novita Sandbox is now a supported backend. Switch providers by changing one string — your rollout and evaluation code stays the same.

## Install

```bash theme={"system"}
pip install 'bespokelabs-sandbox[novita]'
export NOVITA_API_KEY=<YOUR_NOVITA_API_KEY>
```

## Hello, sandbox

```python theme={"system"}
from bespokelabs.sandbox import Sandbox

sb = Sandbox("novita", timeout_secs=600)
try:
    r = sb.execute_code("print(6 * 7)")
    print(r.stdout)                      # 42

    r = sb.execute_command("ls", ["-la", "/tmp"])
    print(r.exit_code, r.stdout)         # non-zero exit codes are returned, not raised

    sb.write_file("/tmp/data.bin", b"\x00\xff")
    assert sb.read_file("/tmp/data.bin") == b"\x00\xff"
finally:
    sb.destroy()   # explicit destroy surfaces errors; context-manager exit is best-effort
```

![Sandbox Router terminal output showing Python returning 42, a successful shell command, and a binary file round-trip](https://mintcdn.com/novitaai/Y1uudO5TkPT1G99w/images/sandbox/sandbox-integrations-sandbox-router-hello.png?fit=max\&auto=format\&n=Y1uudO5TkPT1G99w\&q=85\&s=cae7e36677d6bbe76e49c047e40cb4ce)

## Configuration

| Sandbox(...) argument | Novita SDK | Notes |
| - | - | - |
| `timeout_secs` | `timeout` | Sandbox lifetime in seconds. Router default 600. |
| `template` | `template` | Custom templates must include the Code Interpreter / Jupyter runtime; a plain base image will not work. |
| `env_vars` | `envs` | Environment variables inside the sandbox. |
| `backend_options` | passed through | Merged last; can override anything above. Also accepts connection options: `domain`, `api_key`, `request_timeout`, `headers`, `extra_sandbox_headers`, `proxy`. |

## What you can do

| Operation | Method | Notes |
| - | - | - |
| Run Python | `execute_code(code)` | Python only. Errors return exit\_code 1 with the traceback in stderr. |
| Run shell | `execute_command(cmd, args=None)` | Synchronous. Non-zero exits come back as result fields. |
| Files | `list_files` / `read_file` / `write_file` | Binary-safe. |
| Transfer | `upload_file(local, remote)` / `download_file(remote, local)` | Whole-file transfers. |
| Expose a port | `expose_port(port)` | Returns an HTTPS URL plus the access-token header. See below. |
| Destroy | `destroy()` | Returns False (no error) if the sandbox is already gone. |
| Reconnect | `Sandbox.resume(state)` | See "Reconnecting". |

## Expose a service

Bind your service to `0.0.0.0` inside the sandbox, then expose the port. Protected services require the `Sandbox-Traffic-Access-Token` header, which the router returns for you.

```python theme={"system"}
sb.execute_command("sh", ["-c", "python -m http.server 8000 --bind 0.0.0.0 &"])

ep = sb.expose_port(8000)
print(ep.url)       # https://<host>
print(ep.headers)   # {"Sandbox-Traffic-Access-Token": "..."}

import requests
requests.get(ep.url, headers=ep.headers)
```

Treat the header as a secret. It lives in memory only and is never serialized or logged; requests without it get HTTP 403.

![Sandbox Router expose\_port output showing a service URL, the access header name without its token value, and an HTTP 200 response with Hello from Novita Sandbox](https://mintcdn.com/novitaai/Y1uudO5TkPT1G99w/images/sandbox/sandbox-integrations-sandbox-router-expose-port.png?fit=max\&auto=format\&n=Y1uudO5TkPT1G99w\&q=85\&s=9a3be9c5d049f5e6030b2b447467942f)

## Reconnecting from another process

```python theme={"system"}
state = sb.session_state()     # sandbox_id + domain only, no credentials
# ... restart, hand off to another worker ...
sb2 = Sandbox.resume(state)    # NOVITA_API_KEY must be set in the new process
```

`resume` calls the SDK's `connect(sandbox_id)`. Connecting may extend a running sandbox's expiry and may wake a paused sandbox. Recovery of paused, deleted or expired sandboxes is not guaranteed.

## RL rollouts at scale

The pattern that works: one sandbox per rollout, destroyed when done, with `timeout_secs` set to your task budget.

```python theme={"system"}
from concurrent.futures import ThreadPoolExecutor
from bespokelabs.sandbox import Sandbox

def rollout(task):
    sb = Sandbox("novita", timeout_secs=300, env_vars={"TASK_ID": task.id})
    try:
        sb.upload_file(task.repo_tar, "/workspace/repo.tar")
        sb.execute_command("tar", ["-xf", "/workspace/repo.tar", "-C", "/workspace"])
        r = sb.execute_command("sh", ["-c", task.eval_cmd])
        return task.id, r.exit_code, r.stdout
    finally:
        sb.destroy()

with ThreadPoolExecutor(max_workers=64) as pool:
    results = list(pool.map(rollout, tasks))
```

* Pre-bake dependencies into a custom template (with the Code Interpreter runtime) and pass it via `template=` instead of installing on every rollout.

* Concurrency is bounded by your account quota.

## Current limits

> [!NOTE]
>
> Not supported in this backend today: snapshots, jobs, listing sandboxes, a separate pause/resume API, runtime network policy changes, and generic CPU / RAM / disk / GPU / image mappings. Dockerfiles and restrictive network policies are rejected. `allow_internet=False` is not mapped to any isolation — do not rely on it to cut network access.

## Links

* Repository: [github.com/bespokelabsai/sandbox-router](https://github.com/bespokelabsai/sandbox-router)

* Novita backend PR: [#62](https://github.com/bespokelabsai/sandbox-router/pull/62)

* Backend reference: [docs/BACKENDS.md](https://github.com/bespokelabsai/sandbox-router/blob/main/docs/BACKENDS.md#novita-code-interpreter)

* Issues with the router: [sandbox-router issues](https://github.com/bespokelabsai/sandbox-router/issues). Issues with Novita Sandbox: Novita support.


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