MCP server

Connect Claude, ChatGPT, Claude Code, Codex, Cursor or any MCP client to https://sandboxer.com/mcp and your agent can create cloud sandboxes, run code, move files, publish ports, save snapshots and clean up, with no CLI to install.

.md

Sandboxer's Model Context Protocol server gives an agent its own cloud computers. With it, the agent can:

  • create Linux sandboxes;
  • run commands in them, in the foreground or the background;
  • read and write files;
  • put a port on a public HTTPS URL;
  • save and reuse snapshots;
  • stop or delete sandboxes when it is done.

Everything runs in Sandboxer microVMs, not on your computer.

There are two ways to connect:

  • Hosted at https://sandboxer.com/mcp (Streamable HTTP). Nothing to install. Apps like Claude and ChatGPT sign in with your Sandboxer account (OAuth). Headless clients send an API key.
  • Local with sbx mcp (or npx sandboxer-mcp), a stdio server that ships with the CLI. It has the same 20 tools plus handoff_session, which only works locally.

If you are an agent setting this up#

  1. Add the MCP server https://sandboxer.com/mcp (transport: Streamable HTTP, sometimes labelled "HTTP") to the client you run in. The exact command or config for each client is below.
  2. Authenticate:
    • In an app that can open a browser (Claude, ChatGPT, Claude Code, Codex, Cursor), leave out any key. The client will ask your user to sign in to Sandboxer and click Allow.
    • In a headless run, you need an API key, and you can't create one yourself. Ask your user to create a key at sandboxer.com/app/api-keys (a scoped key, such as the ci preset, is enough) and to put it in the SANDBOXER_API_KEY environment variable of the process you run in. Don't ask them to paste it into the conversation. The config then sends it as Authorization: Bearer <key>, read from that variable, so the key never sits in a file you commit.
  3. Most clients load a new MCP server only after a restart or reconnect. Then check the connection by calling list_sandboxes. An empty list means it works.
  4. Clean up after yourself. stop_sandbox stops billing and keeps everything. delete_sandbox removes the sandbox for good.

Claude (claude.ai and Claude Desktop)#

  1. Open Customize > Connectors (claude.ai/customize/connectors) and click Add custom connector.
  2. Enter the URL https://sandboxer.com/mcp and click Add. If the dialog asks about authentication, choose a sign-in option ("Sign in now" or "Sign in when needed").
  3. Click Connect, sign in to Sandboxer and click Allow.
  4. In a chat, turn the connector on from + > Connectors.

On Team and Enterprise plans, an Owner adds the connector once under Organization settings > Connectors (Add, then Custom), and each member then clicks Connect. If Claude asks how it should identify itself, keep the default (Claude's published identity); Register automatically also works. The free plan allows one custom connector.

ChatGPT#

  1. Open chatgpt.com/plugins, click + and choose Add custom MCP server.
  2. Name it Sandboxer and enter the URL https://sandboxer.com/mcp.
  3. Choose OAuth for authentication, review the warning, select I understand and want to continue, then Create as a plugin.
  4. Sign in to Sandboxer and click Allow.
  5. In a new conversation, type @ and pick Sandboxer.

Your account's or workspace's policies decide whether you can add custom MCP servers. ChatGPT signs in with OAuth rather than taking an API key.

Claude Code#

claude mcp add --transport http --scope user sandboxer https://sandboxer.com/mcp
# then, inside Claude Code: /mcp, choose sandboxer, and sign in

Notes:

  • Keys stay out of the file. Claude Code fills ${SANDBOXER_API_KEY} in from the environment, so the key never lands in .mcp.json or git. Don't pass a key with --header together with --scope project: the shell expands it first, and the literal key would be written to the shared file.
  • A rejected key doesn't fall back to sign-in. Remove the header to sign in instead.
  • Headless runs (claude -p) can't open a browser. Sign in beforehand with claude mcp login sandboxer (add --no-browser over SSH), or use a key.

Codex#

~/.codex/config.toml
[mcp_servers.sandboxer]
url = "https://sandboxer.com/mcp"
bearer_token_env_var = "SANDBOXER_API_KEY"

Codex sends the key in that environment variable as the bearer token. To sign in instead, add the server without bearer_token_env_var and run codex mcp login sandboxer.

Cursor#

~/.cursor/mcp.json
{
  "mcpServers": {
    "sandboxer": {
      "url": "https://sandboxer.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SANDBOXER_API_KEY}" }
    }
  }
}

Use .cursor/mcp.json in a project to add it there only. Cursor fills in ${env:…} from your environment, so the key stays out of the file. To sign in with your Sandboxer account instead, leave out headers, and Cursor opens the sign-in page when it connects.

Any other client#

Point it at https://sandboxer.com/mcp with the Streamable HTTP transport. It authenticates in one of two ways:

  • OAuth 2.1, with PKCE and dynamic client registration or a Client ID Metadata Document. A client discovers it from the 401 and /.well-known/oauth-protected-resource.
  • An API key, sent on every request as Authorization: Bearer <key>.

Sandboxer's MCP server is also listed in the official MCP Registry as com.sandboxer/mcp, with both the hosted endpoint (https://sandboxer.com/mcp) and the npm package (npx -y sandboxer-mcp). Clients that read the registry can install it from there.

When sbx is out of date#

If sbx mcp (the local server) is older than the current release, every tool result ends with a note such as "Note: sbx 5750b620 is out of date; run sbx update (9eff74cd). This MCP server's tools may lack newer options until then." Run sbx update and restart your MCP client. The hosted server (https://sandboxer.com/mcp) is always current.

Keys, scopes and access#

  • Any API key works, including a scoped key. Its scopes apply tool by tool: a key without sandbox.delete can't delete sandboxes (with sandbox.delete-own, as in the ci preset, only the ones it created), and a key limited to certain sandboxes only sees those. Plan limits and rate limits are the same as on the API.
  • Signing in grants the app full access to your account through MCP. The sandboxes it runs bill to your active wallet, as with the CLI.
  • Each connected app is listed under API keys as "Claude (MCP)", "ChatGPT (MCP)" and so on. Disconnect there to end its access at once.
  • A connector's token only works on /mcp, not on the REST API.

Tools#

How sandboxId defaults work:

  • It defaults to the sandbox this connection (MCP session) created or used last, so an agent that creates one sandbox never has to repeat its id. The server remembers that for an hour of inactivity.
  • A fresh connection never picks one of your other sandboxes on its own. If a call says sandboxId is required, pass it explicitly.
  • delete_sandbox always needs an explicit sandboxId.

Sandboxes created through MCP stop automatically after an hour unless ttlSeconds says otherwise. extend_sandbox changes that. A stopped sandbox bills no running time.

(destructive) marks tools that can change or remove data in a sandbox; (read-only) tools change nothing.

Tool What it does Arguments
create_sandbox Create a cloud sandbox (an Ubuntu microVM with root, Docker, git, Node and Python) and wait until it is ready. Returns its id and URL; later calls use it by default. Start from a named snapshot with from (a name, or a versioned name for its newest version) or fromLabels (the newest snapshot with all those labels). optional type, ttlSeconds, name, region, from, fromLabels, labels, env, noEnv, idleStopMinutes
create_task (destructive) Run a coding agent on a GitHub repo in its own sandbox and end in a pull request: it clones the repo onto branch sandboxer/<task-id>, runs the agent on the prompt, commits, opens a PR against the base branch, then pauses. The repo must be connected (the Sandboxer GitHub App installed on it). Follow it with task_status. requires repo, prompt; optional agent, baseBranch
task_status (read-only) Show an agent task: its status (queued, starting, running, committing, opening_pr, paused, failed, cancelled), the pull request once opened, cost so far and any error. requires taskId
list_sandboxes (read-only) List your sandboxes with their state, URL and labels. optional state, labels
get_sandbox (read-only) Show one sandbox: state, URL, when it stops automatically, labels and stored bytes. optional sandboxId
exec (destructive) Run a shell command (bash -c) in the sandbox. By default it waits and returns stdout, stderr and the exit code (timeoutSeconds, default 120, max 600). With detached: true it starts the command in the background and returns its processId at once: read its output and exit code with command_status, stop it with kill_command. Use detached for anything long (builds, test suites, servers). requires command; optional sandboxId, cwd, timeoutSeconds, env, detached
command_status (read-only) Status of a detached command: running or its exit code, and its output. Pass the stdoutOffset/stderrOffset from the previous call to get only new output. requires processId; optional sandboxId, stdoutOffset, stderrOffset
kill_command (destructive) Stop a detached command. requires processId; optional sandboxId
read_file (read-only) Read a file from the sandbox (up to 5 MiB). requires path; optional sandboxId, encoding
write_file (destructive) Create or overwrite a file in the sandbox (up to 5 MiB). Parent directories are created. requires path, content; optional sandboxId, encoding
host_port Serve a port of the sandbox on a stable public HTTPS URL. The URL carries an access token unless public is true. Start the service first, listening on 0.0.0.0 (or set localhost). requires port; optional sandboxId, public, localhost, title
stop_sandbox Snapshot the sandbox (memory included) and stop billing. Files, installed packages and running processes are kept; resume_sandbox brings it back. optional sandboxId
resume_sandbox Resume a stopped sandbox from its snapshot and wait until it is ready. Its memory (running processes) is restored when a machine of its CPU type is free within 2 minutes; otherwise it boots from disk (files intact) and the result says so. requireMemory: true waits up to 30 minutes for its memory instead and fails rather than boot from disk. optional sandboxId, requireMemory
extend_sandbox Set when the sandbox stops: ttlSeconds from now (0 never), and/or idleStopMinutes (pause after that long without activity, waking on use; 0 never). optional sandboxId, ttlSeconds, idleStopMinutes
rename_sandbox Change the sandbox's display name. requires name; optional sandboxId
label_sandbox Replace the sandbox's labels ({} clears them). requires labels; optional sandboxId
delete_sandbox (destructive) Delete a sandbox permanently: its disk, memory and automatic snapshots go (named snapshots saved from it stay). sandboxId is required: there is no default and no wildcard. requires sandboxId
save_snapshot Save the sandbox as a named snapshot to create new sandboxes from, and wait until it is saved. With versioned: true each save is a new version (<name>-v<N>); ifLatest saves only if the newest version is still that number (safe concurrent saves); keep deletes all but the newest N versions. requires name; optional sandboxId, labels, versioned, ifLatest, keep
list_snapshots (read-only) List your named snapshots: name, version, labels, created time, stored bytes (what counts toward your storage) and disk size (logical). optional labels, name
delete_snapshot (destructive) Delete one named snapshot (one version, e.g. ci-base-v3). name is required: there is no wildcard. requires name
handoff_session (destructive) Move this machine's Claude Code or Codex session and its repo into a new sandbox and resume the agent there, headless ("close my laptop"). Checkpoints every change (untracked files too) on a temporary branch without touching the user's branch, pushes it into the sandbox over SSH (never to a remote), moves the session file and resumes it with the account's API key (never a subscription login). .env files always stay behind (copy them with sbx handoff --include-env yourself). Only in the local sbx mcp server. Bring it back with sbx handoff --back. requires cwd; optional agent, session, prompt, model, sandboxId

How results come back:

  • Text and data. Every tool returns a short text summary, and the same data as structuredContent.
  • A non-zero exit code is a normal result, not a tool error, so the agent sees the output and can fix the problem.
  • API failures are tool errors carrying the API's message: an unknown sandbox, a stopped one, a plan or start limit.

Long-running commands and servers#

exec waits up to timeoutSeconds (default 120, at most 600). For longer work, pass detached: true:

  • exec then returns a processId at once.
  • command_status returns new output since the offsets you pass, and the exit code when the command ends.
  • kill_command stops it.

To serve an app, start it detached, listening on 0.0.0.0, then publish its port:

exec       { "command": "npm run dev -- --host 0.0.0.0 --port 3000", "detached": true }
host_port  { "port": 3000 }

The URL carries an access token unless you pass public: true. See Hosting.

Snapshots, labels and versions#

  • Labels: create_sandbox and label_sandbox set them, and list_sandboxes filters by them.
  • Saving: save_snapshot saves the sandbox as a named snapshot. With versioned: true each save is a new version under one name. ifLatest makes concurrent saves safe, and keep keeps only the newest N versions.
  • Starting from a snapshot: create_sandbox takes from (a name, or a versioned name for its newest version) or fromLabels (the newest snapshot carrying all those labels).
  • Listing: list_snapshots shows each snapshot's stored bytes (what counts toward your plan's storage) next to its logical disk size.

Local server (sbx mcp)#

The same tools run as a local stdio server inside the CLI. Install the CLI and sign in once. On Windows, install with irm https://sandboxer.com/install.ps1 | iex.

curl -fsSL https://sandboxer.com/install | sh
sbx login

Then add it to your client:

claude mcp add sandboxer -- sbx mcp

Notes:

  • Without installing the CLI first: npx sandboxer-mcp fetches and starts it. There's no sbx login that way, so set SANDBOXER_API_KEY in its environment. Codex doesn't pass your shell's environment to stdio servers, so list the variable in ~/.codex/config.toml:

    [mcp_servers.sandboxer]
    command = "npx"
    args = ["-y", "sandboxer-mcp"]
    env_vars = ["SANDBOXER_API_KEY"]
    ``` If an older `sbx` on your `PATH` is missing tools, run `sbx self-update`.
    
  • On a server or in CI: skip sbx login and set SANDBOXER_API_KEY in the server's environment.

  • Claude Desktop reads claude_desktop_config.json (Settings > Developer > Edit Config). Desktop apps don't always inherit your shell's PATH, so use the full path from which sbx if the client can't find it.

  • Defaults for the sandboxes the agent creates: sbx mcp --type small --ttl 1800 sets their size and auto-stop in seconds (default 3600; 0 never stops them). The agent can still pass its own values.

  • Organizations: sbx --org acme mcp bills them to the acme wallet. --api-key overrides the signed-in key.

Frameworks#

The same server plugs into agent frameworks that speak MCP:

Each of those pages also shows how to write a code-execution tool directly with the sandboxer-sdk package, for when you don't want an MCP server.