SDKs & MCP

Three ways to use WBX Sandbox: the Python SDK for your own code, the MCP server to give Claude and other AI assistants sandboxes without writing code, and the REST API from any language.

Python SDK

A single small package with no dependencies – it uses only the Python standard library (Python 3.9+).

pip install https://sandbox.wbx.cz/download/wbxsandbox-sdk.tar.gz

Configure

Set two environment variables (or pass url= and api_key= to Sandbox.create):

export WBXSANDBOX_URL=https://sandbox.wbx.cz
export WBXSANDBOX_API_KEY=YOUR_API_KEY

The basics

from wbxsandbox import Sandbox

with Sandbox.create(template="base", timeout=300) as sb:
    # run a shell command and wait for the result
    r = sb.run("python3 --version")
    print(r.exit_code, r.stdout)

    # run a piece of code (python, node or bash)
    r = sb.run_code("print(sum(range(100)))")
    print(r.stdout)                                  # 4950

    # files
    sb.files.write("/home/user/input.txt", "hello")
    print(sb.files.read_text("/home/user/input.txt"))
    print(sb.files.list("/home/user"))
# the sandbox is destroyed when the "with" block ends

Reference

Background jobs

For long or many parallel tasks: one call, no open connection, results kept after the sandbox is gone.

from wbxsandbox import run_job, get_job, run_batch

job = run_job(command="python analyze.py", template="base", timeout_seconds=3600,
              save_artifacts=True, max_cost="0.10")
print(job.id)                                   # returns immediately

job = get_job(job.id).wait()                     # later, from anywhere
print(job.summary()["status"])
job.download("output/report.csv", "report.csv")  # checks the SHA-256

batch = run_batch([{"command": f"python worker.py {i}"} for i in range(100)],
                  defaults={"template": "base", "save_artifacts": True},
                  max_concurrency=10, max_total_cost="2.00")
print(batch.wait().summary()["status"])         # completed / partial / failed

Errors

API errors raise wbxsandbox.SandboxError with status (HTTP status) and message. A command that fails does not raise – check result.exit_code, or call result.check().

from wbxsandbox import Sandbox, SandboxError

try:
    sb = Sandbox.create(template="browser")
except SandboxError as e:
    if e.status == 429:
        print("limit reached:", e.message)   # too many sandboxes for your plan, or no capacity right now
    raise

MCP – connect ChatGPT, Claude and other AI assistants

MCP (Model Context Protocol) lets an AI assistant use external tools. Connect WBX Sandbox and the assistant gets tools to create sandboxes, run commands and code, and read and write files – everything runs on our servers, not on your computer.

The server address is always https://sandbox.wbx.cz/mcp. Assistants that can't send an API key simply ask you to sign in to WBX Sandbox and approve access; this creates an API key named “… (connected app)” in your team. To disconnect, delete that key in API keys. Only team owners and admins can approve.

ChatGPT

1. In ChatGPT open Settings → Apps & Connectors → Advanced settings and turn on Developer mode (the exact names can differ by plan; workspaces may need an admin to allow it).
2. Back in Apps & Connectors choose Create, name it “WBX Sandbox” and enter the URL https://sandbox.wbx.cz/mcp. Authentication: OAuth.
3. ChatGPT opens our sign-in page – sign in and click Allow access.
4. In a new chat enable the connector and ask, for example: “Create a sandbox and compute the 50th Fibonacci number in Python.”

claude.ai and Claude Desktop

Settings → Connectors → Add custom connector, URL https://sandbox.wbx.cz/mcp. Leave the advanced OAuth fields empty – Claude registers itself, opens our sign-in page and you click Allow access.

Claude Code

With an API key in a header (no browser needed – good for servers and CI):

claude mcp add --transport http wbxsandbox https://sandbox.wbx.cz/mcp --header "Authorization: Bearer YOUR_API_KEY"

Or leave out --header and run /mcp in Claude Code to sign in through the browser.

Other MCP clients (stdio)

Download the small helper program and add it to claude_desktop_config.json:

{
  "mcpServers": {
    "wbxsandbox": {
      "command": "/path/to/wbxsandbox-mcp",
      "args": ["-url", "https://sandbox.wbx.cz", "-key", "YOUR_API_KEY"]
    }
  }
}

Helper downloads: macOS (Apple Silicon) · macOS (Intel) · Windows · Linux

Tools the assistant gets

If the assistant doesn't pass a sandbox id, the tools use the last sandbox it created in the conversation (and create one when there is none).

Other languages

Everything the SDK does is plain HTTPS with JSON – see the REST API reference. A minimal example in Node.js (18+, no packages needed):

const API = "https://sandbox.wbx.cz";
const headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" };

const sb = await (await fetch(`${API}/v1/sandboxes`, {
  method: "POST", headers, body: JSON.stringify({ template: "base", timeout_s: 300 }),
})).json();

const r = await (await fetch(`${API}/v1/sandboxes/${sb.id}/exec`, {
  method: "POST", headers, body: JSON.stringify({ cmd: "python3 -c 'print(6*7)'" }),
})).json();
console.log(r.exit_code, r.stdout);          // 0 "42\n"

await fetch(`${API}/v1/sandboxes/${sb.id}`, { method: "DELETE", headers });