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

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.

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