MCP server: runner-mcp

A local MCP server over stdio that gives an AI assistant sandboxes as tools. It holds no state: each tool is a call to the public API with the key it was started with, so the key's scopes are exactly what the assistant may do. Give it a narrow key.

Run it

1RUNNER_API_KEY=rk_... runner-mcp -url https://api.example.com


`RUNNER_API_KEY`	Required; without it the server refuses to start (exit 2).
`-url`	The API (default `$RUNNER_API_URL`, else `http://localhost:8080`). Must be http(s).

{"command": "runner-mcp", "args": ["-url", "..."],
"env": {"RUNNER_API_KEY": "rk_..."}}

. The server name is runner-mcp, version 0.1.0; the published package name is not settled.

Tools

Tool	Scope	What
`sandbox_create`	`sandboxes:write`	Create and wait until running, up to 2 minutes (then `sandbox_not_ready`, carrying the sandbox so you can poll or delete it). Inputs: `template` (required, no default), `vcpus`, `memory_mib`, `disk_mib`, `env`, `metadata`, `network.allow_domains`, `lease_seconds`, `public_ports`.
`sandbox_get`	`sandboxes:read`	A sandbox's state. Input `id`.
`sandbox_renew`	`sandboxes:write`	Extend the lease to `seconds` (60 to 604800) from now. Inputs `id`, `seconds`. Returns `generation` and `expires_at`. Only a renewal extends a lease.
`sandbox_delete`	`sandboxes:write`	Delete. Input `id`. Do this when done: a running sandbox holds a slot.
`exec`	`exec`	Run a command; returns `exit_code`, `reason`, `stdout`, `stderr`, `lost`. Output also streams as progress notifications. Inputs: `sandbox_id`, `cmd`, `args`, `cwd`, `env`, `user`, `timeout_ms`.
`file_read`	`files`	Text as `content`, anything else as `content_base64`. At most 1 MiB.
`file_write`	`files`	Write a text file (`sandbox_id`, `path`, `content`, optional `mode`, `user`); atomic replace.
`file_list`	`files`	List a directory.
`file_remove`	`files`	Remove a file, or a tree with `recursive`.
`template_list`	`templates`	Your templates.
`template_build`	`templates`	Start a build: `name`, `dockerfile`, `tag`, `ready`, `disk_mib`, `args`.
`template_build_logs`	`templates`	Follow a build to its end; returns how it ended and the log's tail. A failed build is a failed result.
`template_build_cancel`	`templates`	`name`, `build`.
`template_versions`	`templates`	Versions and tags.
`template_tag`	`templates`	`name`, `tag`, `version`.

Tool inputs use the API's field names. A tool's output cap is 1 MiB (the rest of an exec's output is counted in lost).

Not exposed as tools: processes, previews, SSH, keys, the file stat/mkdir/move routes, and usage. Use the HTTP API for those.

Errors

A failed tool returns the API's error as its text and structured content, {"error":{"code","message","remedy"}}: branch on code (errors.md). An API that cannot be reached is unavailable. A failed exec that timed out or was OOM-killed also carries result. A failure after a create carries the sandbox.

Ask AI about this page