Agent Sandboxes docs · Start
Connect an agent to sandboxes over MCP
Sandboxes as tools of your agent: add the Pethost Agent Sandboxes MCP server, https://mcp.pethost.dev/sandboxes, to Claude Code, Codex, Cursor or Claude, sign in in your browser, and the agent makes, forks, pauses and deletes sandboxes itself.
- One address:
https://mcp.pethost.dev/sandboxes, streamable HTTP, sign-in by OAuth. No key to paste. - You choose the workspace: the sign-in page offers your workspaces of sandboxes, and the agent's token reaches only those you pick.
- 13 tools for the workspace and each sandbox's record. Commands and files go to the sandbox's own server, which the agent reaches with
ConnectSandboxand thepethostCLI orcurl. - Apart from App Platform: a connector of its own, so an agent set up for one never sees the other's tools.
Step 1: Add the server to Claude Code
claude mcp add --transport http pethost-sandboxes https://mcp.pethost.dev/sandboxes
Or install the plugin, which brings the server and a skill that tells Claude when and how to use sandboxes: claude plugin marketplace add pethost-dev/plugin, then claude plugin install pethost-sandboxes@pethost.
Step 2: Sign in
In Claude Code, run /mcp, pick pethost-sandboxes and authenticate. Your browser opens Pethost's approval page: sign in, choose the workspace of sandboxes the agent may use, and press Connect.
Step 3: Ask for something that needs a computer
“Make a sandbox, clone this repository and run its tests.” The agent reads the workspace, makes a sandbox from base and works in it.
You say: Make a sandbox, clone https://github.com/pallets/click and run its tests.
- CreateSandbox {"name": "click-tests"}
- ConnectSandbox {"sandbox_id": "lelb0x9iq6pvk7t8", "ttl_seconds": 3600}
- Bash curl …/SandboxRuntimeService/RunCommand: git clone -q https://github.com/pallets/click
- Bash curl …/SandboxRuntimeService/RunCommand: python3 -m venv .venv && .venv/bin/pip install -q -e . pytest && .venv/bin/python -m pytest -q
The agent answers: All of click's tests passed in a new sandbox: 2628 passed, 24 skipped, 1 xfailed, 0 failed (pytest exit code 0). … The sandbox will pause after 5 idle minutes and stop after 30, but it isn't deleted automatically. Should I delete it, or keep it for more work?
Codex
The plugin, for the CLI and the desktop app, brings the server and the skill: codex plugin marketplace add pethost-dev/plugin, then codex plugin add pethost-sandboxes@pethost. You sign in in your browser, as with Claude Code, and choose the workspace there.
Cursor
Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project, then turn it on in Cursor's MCP settings, which start the sign-in:
{
"mcpServers": {
"pethost-sandboxes": { "url": "https://mcp.pethost.dev/sandboxes" }
}
}
Claude on the web and on the desktop
In Claude's settings, open Connectors, add a custom connector, and give it the address https://mcp.pethost.dev/sandboxes. Claude opens the sign-in page; then turn the connector on in a conversation.
Any other agent
Any MCP client that speaks streamable HTTP and signs in by OAuth takes the address https://mcp.pethost.dev/sandboxes. Hermes Agent: hermes mcp add pethost-sandboxes --url https://mcp.pethost.dev/sandboxes --auth oauth. The skill, for an agent that reads skills: npx skills add pethost-dev/plugin --skill pethost-sandboxes. An agent given the server alone reads its instructions instead, which say where to start.
The tools
The server's tools are the calls of SandboxService, the panel's half of the API, each with the same name, fields and answers as in the API reference:
| Tool | What it does |
|---|---|
GetWorkspace | The workspace's limits, sizes and prices, its secrets' names and SSH keys. |
ListSandboxes | Its sandboxes, newest first, by state, label or name. |
CreateSandbox | A sandbox from a template, answered once it runs. |
GetSandbox | One sandbox: its state and why, its settings, how to reach it, its usage. |
UpdateSandbox | Its name, size, lifecycle, egress, public ports or environment. |
PauseSandbox | Pause it, memory and processes kept. |
StopSandbox | Stop it, its disk kept. |
ResumeSandbox | Start a paused or stopped one again. |
ForkSandbox | Copy it, memory and processes included, into new sandboxes. |
DeleteSandbox | Delete it, its memory and disk for good. |
ConnectSandbox | The sandbox's server, a token for it and its SSH command. |
CreateTemplate | Save a sandbox's disk as a template. |
ListTemplates | Our templates and the workspace's. |
Commands and files: at the sandbox's own server
What runs inside a sandbox, its commands, files, desktop, links and coding agents, is answered by the server the sandbox runs on, never by the panel. So the MCP server at mcp.pethost.dev/sandboxes lists no RunCommand: the agent calls ConnectSandbox, which answers the server's url, a token for that one sandbox and its ssh_command, and then works there itself:
- With the
pethostCLI, where the agent has a shell:pethost sandbox run <id> -- npm test,pethost sandbox cp ./app <id>:app,pethost sandbox shell <id>. - With
curl, any call ofSandboxRuntimeServiceby its name, in Connect JSON with the field names the tools use. - Without a shell, the agent gives you the sandbox's
panel_url, where its terminal and desktop are, once you sign in.
curl -s "$URL/pethost.sandboxes.v1.SandboxRuntimeService/RunCommand" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"sandbox_id": "'"$ID"'", "command": "npm test"}'
The token is root in that sandbox: the server's instructions and the skill tell the agent to keep it in a shell variable and never to print it in the conversation.
A token for this server alone
The sign-in gives the agent a Pethost API token whose audience is this server: it works at mcp.pethost.dev/sandboxes and at the sandboxes' API, and is refused at App Platform's MCP server, as App Platform's token is refused here. It reaches only the workspaces you picked. Your account's Settings lists it under the agent's name, with what it reaches, and revokes it.
Why it is a connector of its own
App Platform and Agent Sandboxes are two products with different tools and a different reader in mind: an agent that deploys your apps, and an agent that needs computers to run code on. Each has its own server, name, icon, tools and tokens, so an agent set up for one never reads, or confuses, the other's. An account with both adds both: App Platform's is https://mcp.pethost.dev/mcp.
When it does not work
- The sign-in page offers no workspace: it offers workspaces of sandboxes alone. Make one in the console first, choosing Agent Sandboxes.
- The agent says it is not signed in, or its calls answer 401: the token was revoked, or the agent signed in to App Platform's server. Sign in again from the agent (
/mcpin Claude Code). - A tool answers
WorkspaceChoice: the token reaches several workspaces of sandboxes. Tell the agent which one; it sends itsworkspacein every call. - The agent looks for
RunCommand: it is not a tool of this server. Point it atConnectSandboxand the CLI, or install the plugin, whose skill says so. RESOURCE_EXHAUSTEDwithLimitReached: the workspace's vCPUs are held by its running and paused sandboxes. Ask the agent to delete the ones it no longer needs.
Questions
What is the MCP server's address?
https://mcp.pethost.dev/sandboxes, streamable HTTP, signed in by OAuth in your browser.
Which agents work with Pethost Agent Sandboxes?
Any agent that takes a remote MCP server: Claude Code, Codex, Cursor, Claude on the web and desktop, Hermes Agent and others. Claude Code and Codex can install the plugin, which adds a skill.
Can the agent run commands in a sandbox over MCP?
Through the sandbox's own server: ConnectSandbox gives its address and a token, and the agent runs commands with the pethost CLI or curl. The MCP server itself makes, changes, pauses, forks and deletes sandboxes.
Does the agent get my API keys?
No. It gets a token for the workspaces you pick. Keys for models and services are workspace secrets, which no sandbox and no tool answer ever holds.
Is it the same server as Pethost App Platform's?
No: App Platform's is https://mcp.pethost.dev/mcp. Each has its own tools and tokens.
Try Pethost Agent Sandboxes
A 7-day trial with $1 of usage and 4 vCPUs, with a card. Then a plan from $20 a month, which includes as much usage.