WBX Sandbox
Reference

MCP server and tools

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, read and write files and run background jobs – everything runs on our servers, not on your computer.

Setting up an assistant? Step-by-step instructions for ChatGPT, Claude, Claude Code, Cursor, VS Code, Codex, Gemini CLI and others are on Connect your AI.

Server address and sign-in

  • The server address is always https://sandbox.wbx.cz/mcp (Streamable HTTP).
  • Assistants that can't send an API key ask you to sign in to WBX Sandbox and approve access (OAuth); 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.
  • Clients that can send headers can use an API key directly: Authorization: Bearer YOUR_API_KEY.
claude mcp add --transport http wbxsandbox https://sandbox.wbx.cz/mcp --header "Authorization: Bearer YOUR_API_KEY"

Local helper for stdio clients

For clients that can only start a local program. Download the small helper program and add it to your client's configuration, for example claude_desktop_config.json:

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

Helper downloads: macOS (Apple Silicon) · macOS (Intel) · Windows · Linux (x86-64) · Linux (ARM64) · SHA-256 checksums

Keep the API key in env, not in args – arguments are visible to other programs on the computer. On macOS and Linux make the file executable with chmod +x; on macOS also allow it with xattr -d com.apple.quarantine wbxsandbox-mcp-darwin-arm64. Windows may show a SmartScreen warning for the downloaded program. wbxsandbox-mcp -version prints the version; download it again after an update to get new tools.

Tools

ToolWhat it does
create_sandboxStart a sandbox from a template – optionally without internet, with allowed destinations only, or with IPv6 (ip: dual or ipv6). With a name, an existing sandbox of that name is reused (woken up if asleep), so files survive between chats
run_commandRun a shell command
run_codeRun Python, JavaScript or bash code
write_file / read_fileUpload and read files (writing creates missing directories)
list_files / delete_pathList a directory, delete a file or directory
list_sandboxes / list_templatesSee running and sleeping sandboxes and available templates
set_timeoutExtend a sandbox's lifetime
get_public_urlHTTPS address of a web app or API running in the sandbox
pause_sandbox / resume_sandboxPut a sandbox to sleep (files kept, programs stop, no compute billed) and wake it up – any command wakes it too. Sandboxes from the assistant fall asleep after their lifetime or 10 minutes without commands instead of being destroyed
kill_sandboxDestroy a sandbox (also a sleeping one)
run_job / get_job_summaryRun a command as a background job and check on it later – detail: short (next step), full (complete record with all result files) or receipt (execution receipt with the exact template build and checksums – the signed version is available over the REST API, the Python SDK or in the portal). Also download_job_artifact, cancel_job, retry_job
list_jobsYour recent jobs or batches, newest first – filter by state, batch or time (since: 24h, 7d …), paged
wait_jobsWait until a job or batch finishes – the assistant does not have to keep asking
get_job_logsA compact log digest by default: recognised test results, errors with context and the end of the log (mode=raw for raw bytes)
run_batch / get_batch_summary / cancel_batchRun many jobs at once with a concurrency and price limit, see the aggregated result
get_budgetYour spending limits, spend and reservations
get_compute_classesCompute classes available to you and your default class

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).

Sandboxes created over MCP fall asleep after their lifetime or 10 minutes without commands instead of being destroyed – see Sleep and wake. Command output, file contents and logs are returned to the assistant as data from the sandbox.