Sandboxes MCP server
The sandbox runtime exposes its own MCP (Model Context Protocol) server, separate from the platform one. Connect Claude Code, Claude Desktop, Cursor, Windsurf, or any MCP client and an agent can create sandboxes, run code in them, move files, and pause or terminate them - all as tool calls.
At a glance
- Endpoint:
https://orkestr.eu/api/sandboxes/mcp - Transport: Streamable HTTP
- Auth: Bearer API token with a sandbox scope
- Tools: 18, covering the full sandbox, template, and volume lifecycle
Setup
Enable sandboxes from the Sandboxes console, then mint an API token (Settings -> API) that includes the sandboxes:read and sandboxes:write scopes. Add one of the snippets below to your MCP client and replace ork_your_token_here with that token.
Claude Code CLI - one-liner
claude mcp add --transport http orkestr-sandboxes https://orkestr.eu/api/sandboxes/mcp \
--header "Authorization: Bearer ork_your_token_here"Claude Desktop / Claude Code config
Paste into ~/.claude.json (Claude Code) or claude_desktop_config.json (Claude Desktop). Restart the client to load the new MCP.
{
"mcpServers": {
"orkestr-sandboxes": {
"command": "npx",
"args": [
"mcp-remote",
"https://orkestr.eu/api/sandboxes/mcp",
"--header",
"Authorization: Bearer ork_your_token_here"
]
}
}
}Cursor
Paste into .cursor/mcp.json at the root of your workspace. Restart Cursor.
{
"mcpServers": {
"orkestr-sandboxes": {
"url": "https://orkestr.eu/api/sandboxes/mcp",
"headers": {
"Authorization": "Bearer ork_your_token_here"
}
}
}
}Scopes
Each tool needs the matching scope on your token. A read-only token (sandboxes:read) can inspect limits, read files, and list directories but cannot create or mutate a sandbox. Grant sandboxes:write for the full set.
Available tools
Every tool delegates to the same /v1/sandboxes REST routes, so plan limits, ownership checks, and error handling are identical to the SDK and API. run_code adapts to the sandbox: on the code-interpreter template, Python executes in a persistent kernel - variables survive across calls, exceptions come back structured, and chart PNGs are saved into the sandbox and returned as a png_path readable with read_file (base64 blobs would drown an agent transcript). On other templates - and for Node and bash - it runs the snippet as a one-shot process, exactly as before. See Code interpreter.
create_sandboxwriteCreate a sandbox - an isolated, ephemeral Linux environment.get_sandbox_limitsreadReport the sandbox sizes and limits available on your plan.run_shellwriteRun a shell command in a sandbox; returns stdout, stderr, exit code.run_codewriteRun a snippet of Python, Node, or bash. On code-interpreter sandboxes, Python runs in a persistent kernel: variables survive across calls and results come back rich.start_background_commandwriteStart a long-running command in the background and get a handle back immediately - builds, installs, test suites, dev servers. Survives pause/resume.list_background_commandsreadList every background command in a sandbox with live status.get_background_commandreadPoll one background command's status and exit code.get_command_logsreadRead a background command's combined output from a byte offset.kill_background_commandwriteStop a background command (SIGTERM, then SIGKILL). Idempotent.write_filewriteWrite a text file into a sandbox.read_filereadRead a text file from a sandbox.list_filesreadList the entries of a directory in a sandbox.get_sandbox_hostreadGet the public URL for a port the sandbox is serving (needs a networked, paid sandbox).pause_sandboxwriteSnapshot a sandbox and stop its compute meter.resume_sandboxwriteResume a paused sandbox, restoring its snapshot.terminate_sandboxwriteTerminate a sandbox and free its resources (irreversible).create_templatewriteBuild a custom template - preinstall deps in a build VM, then boot sandboxes from it (paid plans).list_templatesreadList your custom templates and their build status (building / ready / failed).delete_templatewriteDelete a custom template and its image (irreversible).create_volumewriteCreate a persistent volume - storage mounted at /persist that survives across sandboxes; optionally pin its region.list_volumesreadList your persistent volumes and their status / attachment.move_volumewriteMove a detached persistent volume to another region (data follows via its object-storage checkpoint).delete_volumewriteDelete a persistent volume and its data (irreversible; rejected while attached).Example prompts
Once connected, use natural language. The model picks the right tool, fills in the arguments from context, and you see the result.
“Create a python-3.12 sandbox and run this script in it”
Creates a sandbox, writes the file, and execs it - returning stdout and the exit code.
“Run this untrusted code somewhere isolated and tell me what it prints”
Spins up a fresh sandbox, runs the code, and tears it down.
“Pause that sandbox - I will come back to it later”
Snapshots the sandbox so it stops billing and can be resumed with its state intact.
“What sandbox sizes can I create on my plan?”
Calls get_sandbox_limits and reports allowed sizes plus your monthly budget.
“Build a python-3.12 template with pandas and pyarrow preinstalled, then run my notebook in it”
Calls create_template, polls list_templates until it is ready, then creates a sandbox from it - deps already installed.
“Save these results to a volume so the next run can pick them up”
Creates a sandbox with volume set, writes under /persist; a later sandbox naming the same volume gets the data back (survives terminate).
New to sandboxes? Start with the quickstart or the REST API reference.