Sandboxes

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.

Two separate MCP servers

This is the sandbox-runtime MCP. Project, deployment, and infrastructure management live on the separate platform MCP server. They have intentionally different blast radius: an agent given only the sandbox MCP can run code in a sandbox but cannot touch your projects or deployments.

At a glance

Endpoint: https://orkestr.eu/api/sandboxes/mcp
Transport: Streamable HTTP
Auth: Bearer API token with a sandbox scope
Tools: 10, covering the full sandbox lifecycle

Setup

Enroll in the sandbox beta 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

terminal

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.

claude_desktop_config.json

{
  "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.

.cursor/mcp.json

{
  "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.

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 in a sandbox.

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.

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

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.

Mint a dedicated token

Use a token scoped to sandboxes only for the MCP connection - not a wildcard token. An agent driving this server can run arbitrary code inside your sandboxes and spend your monthly compute budget; keep its reach to exactly that, and revoke the token if the machine it lives on is ever lost.

New to sandboxes? Start with the quickstart or the REST API reference.