English
Docs menu

Agent Sandboxes docs · Start

Connect an agent to sandboxes over MCP

Updated · 6 min read

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.

In short
  • 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 ConnectSandbox and the pethost CLI or curl.
  • 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.

Claude Code

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:

ToolWhat it does
GetWorkspaceThe workspace's limits, sizes and prices, its secrets' names and SSH keys.
ListSandboxesIts sandboxes, newest first, by state, label or name.
CreateSandboxA sandbox from a template, answered once it runs.
GetSandboxOne sandbox: its state and why, its settings, how to reach it, its usage.
UpdateSandboxIts name, size, lifecycle, egress, public ports or environment.
PauseSandboxPause it, memory and processes kept.
StopSandboxStop it, its disk kept.
ResumeSandboxStart a paused or stopped one again.
ForkSandboxCopy it, memory and processes included, into new sandboxes.
DeleteSandboxDelete it, its memory and disk for good.
ConnectSandboxThe sandbox's server, a token for it and its SSH command.
CreateTemplateSave a sandbox's disk as a template.
ListTemplatesOur 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 pethost CLI, 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 of SandboxRuntimeService by 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 (/mcp in Claude Code).
  • A tool answers WorkspaceChoice: the token reaches several workspaces of sandboxes. Tell the agent which one; it sends its workspace in every call.
  • The agent looks for RunCommand: it is not a tool of this server. Point it at ConnectSandbox and the CLI, or install the plugin, whose skill says so.
  • RESOURCE_EXHAUSTED with LimitReached: 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.

Start the trial