runloop-mcp
This server provides MCP tools to manage Runloop Devboxes, enabling AI agents to create and control isolated Linux sandboxes.
Devbox Lifecycle Management
create_devbox: Create with blueprint, resources, environment variables, startup commands, and idle policy.list_devboxes: List all devboxes, filter by status.get_devbox: Retrieve details for a single devbox.update_devbox: Update name and metadata.suspend_devbox/resume_devbox: Suspend and resume a devbox while preserving disk state.shutdown_devbox: Shut down and delete a devbox.
Command Execution & File Operations
execute_command: Run a command synchronously; returns stdout, stderr, and exit code; supports stateful named shells.execute_command_async: Start a long-running command and get an execution ID.write_file: Create or overwrite a file on the devbox.read_file: Read a file’s contents.
Disk Snapshots
create_snapshot: Take a disk snapshot of a devbox.list_snapshots: List available snapshots.
Interactive PTY Sessions
pty_connect: Create/reconnect to a PTY session, get a WebSocket URL.pty_send_command: Send a command through the PTY; ideal for TTY-aware programs.pty_control: Control session (resize, send signal, close).
Allows creating and managing Runloop Devboxes, executing commands, transferring files, creating snapshots, and driving interactive PTY sessions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@runloop-mcp Create a devbox and run 'python3 --version'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Reuse a compatible running sandbox, or create one, then run a command |
| Start a sandbox for a multi-step test, capped at 1 hour |
| List sandboxes while excluding shutdown entries |
| Check sandbox status |
| Preserve and restore sandbox disk state |
| Run a blocking, non-interactive command |
| Upload Base64 test input or source files |
| Export a result before the sandbox disappears |
| Inspect CPU, memory, disk, and usage |
| Destroy a sandbox and its remaining data |
| Save and discover reusable disk states |
| 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 8000stdio:
RUNLOOP_API_KEY=... runloop-mcp --transport stdioThe HTTP MCP endpoint is /mcp. Supply the API key when connecting:
http://127.0.0.1:8000/mcp?api_key=YOUR_RUNLOOP_API_KEYDo 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_codeonly reuses running sandboxes tagged withpurpose=code-testing.It prefers a sandbox matching the requested blueprint.
Files passed to
run_codeoverwrite 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_codeattempts 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 8000The included Dockerfile uses the same ASGI application.
License
Available Tools
16 toolscreate_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
Scored across 16 tools
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.
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.
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.
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
Secure Linux sandboxes for AI agents, as MCP tools.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseBqualityDmaintenanceProduction-grade MCP server that gives AI agents safe access to your local dev environment: filesystem, databases, processes, and OpenAPI specs.1540 npm4MIT
- AlicenseCqualityDmaintenanceA security-first MCP server that provides LLMs with structured tools for filesystem, process, search, build/test/lint, IDE integration, and more.402PolyForm Noncommercial 1.0.0
- FlicenseAqualityDmaintenanceA simple MCP server that exposes a terminal tool, allowing AI agents to execute shell commands.1-
- FlicenseBqualityCmaintenanceA lightweight MCP server that enables AI assistants to interact with the local machine through terminal, filesystem, and Python execution tools.9-