# Sandboxes MCP server

The sandbox runtime exposes its own [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 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](https://orkestr.eu/docs/mcp). 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:** 18, covering the full sandbox, template, and volume lifecycle

## Setup

Enable sandboxes from the [Sandboxes console](https://orkestr.eu/sandbox), 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

```bash
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.

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

```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. `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](https://orkestr.eu/docs/sandboxes/code-interpreter).

`create_sandbox`writeCreate a sandbox - an isolated, ephemeral Linux environment.

`get_sandbox_limits`readReport the sandbox sizes and limits available on your plan.

`run_shell`writeRun a shell command in a sandbox; returns stdout, stderr, exit code.

`run_code`writeRun 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_command`writeStart a long-running command in the background and get a handle back immediately - builds, installs, test suites, dev servers. Survives pause/resume.

`list_background_commands`readList every background command in a sandbox with live status.

`get_background_command`readPoll one background command's status and exit code.

`get_command_logs`readRead a background command's combined output from a byte offset.

`kill_background_command`writeStop a background command (SIGTERM, then SIGKILL). Idempotent.

`write_file`writeWrite a text file into a sandbox.

`read_file`readRead a text file from a sandbox.

`list_files`readList the entries of a directory in a sandbox.

`get_sandbox_host`readGet the public URL for a port the sandbox is serving (needs a networked, paid sandbox).

`pause_sandbox`writeSnapshot a sandbox and stop its compute meter.

`resume_sandbox`writeResume a paused sandbox, restoring its snapshot.

`terminate_sandbox`writeTerminate a sandbox and free its resources (irreversible).

`create_template`writeBuild a custom template - preinstall deps in a build VM, then boot sandboxes from it (paid plans).

`list_templates`readList your custom templates and their build status (building / ready / failed).

`delete_template`writeDelete a custom template and its image (irreversible).

`create_volume`writeCreate a persistent volume - storage mounted at /persist that survives across sandboxes; optionally pin its region.

`list_volumes`readList your persistent volumes and their status / attachment.

`move_volume`writeMove a detached persistent volume to another region (data follows via its object-storage checkpoint).

`delete_volume`writeDelete 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).

> **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](https://orkestr.eu/docs/sandboxes/quickstart) or the [REST API reference](https://orkestr.eu/docs/sandboxes/api-reference).