Skip to main content
Glama

runloop-mcp

An MCP server for running and testing code in disposable Runloop sandboxes. It remains focused on testing rather than vibe coding: active Devboxes last at most one hour and local files should be treated as temporary. Snapshots, blueprints and suspend/resume are available for repeatable test environments; interactive PTYs, tunnels, account secrets and MCP Hub administration are not.

Tools

Tool

Purpose

run_code

Reuse a compatible running sandbox, or create one, then run a command

create_sandbox

Start a sandbox for a multi-step test, capped at 1 hour

list_sandbox

List sandboxes while excluding shutdown entries

get_sandbox

Check sandbox status

suspend_sandbox / resume_sandbox

Preserve and restore sandbox disk state

execute_in_sandbox

Run a blocking, non-interactive command

upload_test_file

Upload Base64 test input or source files

download_artifact

Export a result before the sandbox disappears

get_sandbox_usage

Inspect CPU, memory, disk, and usage

shutdown_sandbox

Destroy a sandbox and its remaining data

create_snapshot / list_snapshot

Save and discover reusable disk states

build_blueprint / list_blueprint

Build and discover reusable test images

Prefer run_code. It searches running code-testing sandboxes first and retains the selected sandbox after a successful run for later reuse. Use shutdown_sandbox when reuse is no longer needed.

Related MCP server: GPT Commander

Installation

Requires Python 3.10+ and a Runloop API key.

pip install -e .

Start

HTTP (default):

runloop-mcp --host 127.0.0.1 --port 8000

stdio:

RUNLOOP_API_KEY=... runloop-mcp --transport stdio

The HTTP MCP endpoint is /mcp. Supply the API key when connecting:

http://127.0.0.1:8000/mcp?api_key=YOUR_RUNLOOP_API_KEY

Do not log or share URLs containing the key. Query-key behavior remains for compatibility, but a secret-aware proxy is recommended for public deployment.

Examples

One-shot Python test:

run_code(
    files={
        "/home/user/test_app.py": "assert 2 + 2 == 4\nprint('passed')\n"
    },
    command="python3 /home/user/test_app.py",
)

Multi-step test with an exported report:

sandbox = create_sandbox(files={"/home/user/package.json": "{...}"})
execute_in_sandbox(sandbox_id=sandbox["id"], command="cd /home/user && npm test")
download_artifact(sandbox_id=sandbox["id"], file_path="/home/user/report.xml")
shutdown_sandbox(sandbox_id=sandbox["id"])

download_artifact returns standard Base64. Decode and save it outside Runloop before shutdown or expiry. Package large source trees into an archive, upload it, and extract it with execute_in_sandbox.

Reuse behavior

  • run_code only reuses running sandboxes tagged with purpose=code-testing.

  • It prefers a sandbox matching the requested blueprint.

  • Files passed to run_code overwrite paths in a reused sandbox.

  • Environment variables are creation-time settings and cannot be replaced when reusing a sandbox; put per-run values in the command when appropriate.

  • A newly created sandbox is destroyed if execution raises an error, but is retained after success.

Design constraints

  • Sandbox lifetime is restricted to 60–3600 seconds.

  • run_code attempts forced cleanup of a newly created sandbox on execution failure.

  • No background-process, PTY, or tunnel workflow is exposed.

  • Sandbox storage must not be treated as a source of truth.

  • Avoid passing credentials in ordinary environment variables or command text.

Deployment

main.py exposes MCP at /mcp and health checks at /health:

uvicorn main:app --host 0.0.0.0 --port 8000

The included Dockerfile uses the same ASGI application.

License

MIT

Available Tools

16 tools
create_devboxB

Create a new Runloop Devbox.

Inputs: name, metadata, after_idle, file_mounts, +8 more. Returns: object

create_snapshotA

Create a disk snapshot of a devbox's current state.

Snapshots persist and accrue storage charges until explicitly deleted. A new devbox can later be created from the snapshot via snapshot_id.

Inputs: devbox_id (required), name, metadata, commit_message. Returns: object

execute_commandA

Execute a command on a devbox and block until it completes.

Each call spawns an isolated shell by default - env vars and CWD do not persist between calls. Pass the same shell_name to reuse a stateful named shell session.

Inputs: command (required), devbox_id (required), shell_name, timeout_seconds. Returns: object

execute_command_asyncA

Start a command on a devbox and return immediately.

Use this for long-running or background processes (servers, watchers). The returned execution_id can be polled later.

Inputs: command (required), devbox_id (required), shell_name. Returns: object

get_devboxA

Retrieve details for a single devbox by id.

Inputs: devbox_id (required). Returns: object

list_devboxesB

List devboxes on the account.

Inputs: limit, status, starting_after. Returns: result

list_snapshotsA

List disk snapshots, optionally filtered to a devbox.

Inputs: limit, devbox_id. Returns: result

pty_connectA

Create or reconnect to an interactive PTY session on a devbox.

Reusing the same session_name reconnects to the same logical PTY session while it is still alive. The returned connect_url is the WebSocket endpoint used by pty_send_command.

Inputs: session_name (required), cols, rows. Returns: object

pty_controlA

Control an existing PTY session: resize, signal, or close.

Inputs: action (required), session_name (required), cols, rows, +1 more. Returns: object

pty_send_commandA

Send a command to an interactive PTY session and capture its output.

Creates the session if it does not exist (or reconnects if it does), opens the WebSocket data plane, writes the command, and reads output until the terminal is quiet for idle_timeout seconds (or max_wait elapses).

Prefer execute_command for non-interactive commands; use this for TTY-aware programs (REPLs, TUIs, interactive shells).

Inputs: command (required), session_name (required), cols, rows, +2 more. Returns: object

read_fileB

Read the contents of a file on a devbox.

Inputs: devbox_id (required), file_path (required). Returns: result

resume_devboxA

Resume a suspended devbox.

Inputs: devbox_id (required). Returns: object

shutdown_devboxA

Shut down (delete) a devbox and release its resources.

Inputs: devbox_id (required), force. Returns: object

suspend_devboxA

Suspend a devbox, preserving its disk state.

In-memory state (running processes, env vars) is lost; restart background processes after resuming.

Inputs: devbox_id (required). Returns: object

update_devboxA

Update a devbox's name and/or metadata.

Inputs: devbox_id (required), name, metadata. Returns: object

write_fileA

Create or overwrite a file on a devbox.

Use this to write new files or edit existing ones (the full contents are written atomically).

Inputs: contents (required), devbox_id (required), file_path (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool maps to a distinct resource and action. The three command execution tools are clearly differentiated by blocking vs async vs interactive PTY, and the PTY tools have separate connect/send/control roles. No two tools appear to do the same thing.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (e.g., create_devbox, list_devboxes, write_file, pty_connect). The PTY tools use a common pty_ prefix, and the async variant uses a clear _async suffix.

    Tool Count5/5

    16 tools cover the devbox lifecycle, file operations, snapshots, and PTY interactivity without redundancy. Even though slightly above the typical range, each tool serves a distinct purpose and the set feels well-scoped.

    Completeness3/5

    Core devbox lifecycle is fully covered (create/get/list/update/suspend/resume/delete). However, there are notable gaps: no way to retrieve results from execute_command_async (no polling/status tool), and no delete operation for snapshots. These are workable but missing.

    Related MCP Connectors

    Related MCP Servers