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.
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(ornpx sandboxer-mcp), a stdio server that ships with the CLI. It has the same 20 tools plushandoff_session, which only works locally.
If you are an agent setting this up#
- 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. - 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
cipreset, is enough) and to put it in theSANDBOXER_API_KEYenvironment variable of the process you run in. Don't ask them to paste it into the conversation. The config then sends it asAuthorization: Bearer <key>, read from that variable, so the key never sits in a file you commit.
- 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. - Clean up after yourself.
stop_sandboxstops billing and keeps everything.delete_sandboxremoves the sandbox for good.
Claude (claude.ai and Claude Desktop)#
- Open Customize > Connectors (claude.ai/customize/connectors) and click Add custom connector.
- Enter the URL
https://sandboxer.com/mcpand click Add. If the dialog asks about authentication, choose a sign-in option ("Sign in now" or "Sign in when needed"). - Click Connect, sign in to Sandboxer and click Allow.
- 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#
- Open chatgpt.com/plugins, click + and choose Add custom MCP server.
- Name it Sandboxer and enter the URL
https://sandboxer.com/mcp. - Choose OAuth for authentication, review the warning, select I understand and want to continue, then Create as a plugin.
- Sign in to Sandboxer and click Allow.
- 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 inNotes:
- Keys stay out of the file. Claude Code fills
${SANDBOXER_API_KEY}in from the environment, so the key never lands in.mcp.jsonor git. Don't pass a key with--headertogether 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 withclaude mcp login sandboxer(add--no-browserover SSH), or use a key.
Codex#
[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#
{
"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
401and/.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.deletecan't delete sandboxes (withsandbox.delete-own, as in thecipreset, 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
sandboxIdis required, pass it explicitly. delete_sandboxalways needs an explicitsandboxId.
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:
execthen returns aprocessIdat once.command_statusreturns new output since the offsets you pass, and the exit code when the command ends.kill_commandstops 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_sandboxandlabel_sandboxset them, andlist_sandboxesfilters by them. - Saving:
save_snapshotsaves the sandbox as a named snapshot. Withversioned: trueeach save is a new version under one name.ifLatestmakes concurrent saves safe, andkeepkeeps only the newest N versions. - Starting from a snapshot:
create_sandboxtakesfrom(a name, or a versioned name for its newest version) orfromLabels(the newest snapshot carrying all those labels). - Listing:
list_snapshotsshows 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 loginThen add it to your client:
claude mcp add sandboxer -- sbx mcpNotes:
Without installing the CLI first:
npx sandboxer-mcpfetches and starts it. There's nosbx loginthat way, so setSANDBOXER_API_KEYin 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 loginand setSANDBOXER_API_KEYin the server's environment.Claude Desktop reads
claude_desktop_config.json(Settings > Developer > Edit Config). Desktop apps don't always inherit your shell'sPATH, so use the full path fromwhich sbxif the client can't find it.Defaults for the sandboxes the agent creates:
sbx mcp --type small --ttl 1800sets their size and auto-stop in seconds (default 3600;0never stops them). The agent can still pass its own values.Organizations:
sbx --org acme mcpbills them to theacmewallet.--api-keyoverrides 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.