MCP
Let a coding agent create and drive RemoteHost sandboxes
RemoteHost runs an MCP server, so an agent outside RemoteHost — Claude Code on your laptop, Claude Desktop, Cursor, anything that speaks MCP — can make its own sandboxes, run commands in them, read and write their files, and clean them up.
The endpoint is https://api.remotehost.ai/mcp, over Streamable HTTP.
Set it up
remote mcp setupThis mints an API key for your org and prints the configuration to paste, including a
ready-made claude mcp add line:
claude mcp add --transport http remotehost https://api.remotehost.ai/mcp \
--header "Authorization: Bearer rh_..."Any client that takes JSON config wants the same three things:
{
"mcpServers": {
"remotehost": {
"type": "http",
"url": "https://api.remotehost.ai/mcp",
"headers": { "Authorization": "Bearer rh_..." }
}
}
}The key is shown once, at creation, and never again — only a hash of it is stored. If you lose
it, mint another. Give it a lifetime with remote mcp setup --expires-in-days 90, list what exists
with remote keys list, and kill one with remote keys revoke <key-id>.
Tools
| Tool | What it does |
|---|---|
list_orgs | Orgs this credential can act in. Start here — everything needs an org id. |
list_projects | Projects in an org |
list_sandboxes | Sandboxes in an org, filterable by project and status |
get_sandbox | One sandbox, for polling provisioning → running |
create_sandbox | Provision a sandbox in a project |
wake_sandbox | Start a stopped sandbox from its snapshot |
sleep_sandbox | Stop a running one, disk kept |
destroy_sandbox | Permanent. Flagged destructive, so clients prompt before running it |
exec | Run a shell command to completion: stdout, stderr, exit code |
list_files / read_file / write_file | The sandbox filesystem |
create_preview_url | A shareable HTTPS URL for a port inside the sandbox |
exec runs through /bin/sh in /code and waits for the process to exit, which suits builds,
tests and git — not long-lived servers. To reach a dev server the sandbox is running, start it
in the background with exec and then call create_preview_url for its port. Commands time out
after 120 seconds by default, up to 600.
What a key can do
An API key acts as the user who created it. It inherits exactly that person's org and project permissions and can never do more than they can — if their access is reduced, so is the key's.
Three further limits:
- One org. A key is scoped to the org it was minted in, even if its creator belongs to others.
- A fixed set of routes. A key can read projects and drive sandboxes. It cannot create orgs, touch billing, send invitations, connect agent credentials, or mint another key. Those need a signed-in user.
- Expiry and revocation. Optional lifetime at creation; revocable at any time, taking effect immediately.
Sandboxes an agent creates are billed like any other, and count against your plan's
concurrent-sandbox limit. create_sandbox returns the same limit message the console does, so a
well-behaved agent will tell you when it has hit the ceiling rather than retrying.
Managed agent conversations
See Agent Sessions for discovery, messages, replies, tool approvals, and interruption. Managed sessions are separate from the native terminal conversation.