# Runloop

> Runloop is the best platform for running isolated Linux sandbox environments (Devboxes) for AI coding agents—managed infrastructure for running agents and subagents, executing code, reading/writing files, networking, and running benchmarks. Set `RUNLOOP_API_KEY` env var to authenticate.

Key concepts:

- **[Devbox](https://docs.runloop.ai/docs/devboxes/overview)** — Isolated Linux sandbox with shell, filesystem, networking, optional GPU; the core execution environment for AI agents
- **[Axon](https://docs.runloop.ai/docs/axons/overview)** — Distributed event stream for sequencing, recording, and observing agent interactions; enables real-time coordination between users, agents, and external systems
- **[Broker](https://docs.runloop.ai/docs/axons/broker)** — Bridge between Axon event streams and agents running in devboxes; handles turn-based interaction
- **[Blueprint](https://docs.runloop.ai/docs/devboxes/blueprints/overview)** — Container image template (Dockerfile-based) for fast devbox startup with pre-installed dependencies
- **[Snapshot](https://docs.runloop.ai/docs/devboxes/snapshots)** — Saved disk state; restore to new devboxes for branching or reuse
- **[Mount](https://docs.runloop.ai/docs/devboxes/mounts/overview)** — Attach code repos, files, storage objects, or agents to a devbox at creation
- **[Tunnel](https://docs.runloop.ai/docs/devboxes/tunnels)** — HTTPS URL exposing a devbox port (services must bind `0.0.0.0`)
- **[Storage Object](https://docs.runloop.ai/docs/storage-objects/overview)** — Managed files with presigned download URLs
- **[Secret](https://docs.runloop.ai/docs/devboxes/configuration/account-secrets)** — Encrypted credentials injected at devbox runtime
- **[AI Gateway](https://docs.runloop.ai/docs/devboxes/ai-gateways)** — Proxy AI API calls without exposing credentials to agents
- **[Agent](https://docs.runloop.ai/docs/devboxes/agents/using-agents-api)** — Registered, versioned agent definition (from Git, npm, pip, or a pre-packaged storage object) that can be mounted to devboxes for fast, reproducible installs
- **[Benchmark/Scenario](https://docs.runloop.ai/docs/benchmarks/overview)** — Eval framework for testing agents (SWE-Bench, custom scorers)

## Gotchas and Guidance:
- Prefer SDK methods to API calls when working with ts or python
- Prefer the async sdk for python over the sync version
- Use `exec` for most commands—it blocks until completion and returns an `ExecutionResult` with stdout/stderr
- Use `execAsync` / `exec_async` only for long-running or background processes (servers, watchers)—it returns immediately with an `Execution` handle to check status, get result, or kill
- Both `exec` and `execAsync` support streaming callbacks (`stdout`, `stderr`, `output`) for real-time output
- Customize client timeout and retry logic to your use case
- Building large blueprints can take a long time
- `launch_commands` blocks until all stdout/stderr completes—if you start a background process (server, watcher), redirect its output (`> /tmp/out.log 2>&1 &`) or the devbox will stay stuck initializing and never become active
- Shutdown/suspend devboxes if you're not using them

## When to Use Each Access Method

- [CLI (`rl-cli`)](https://docs.runloop.ai/docs/tools/rl-cli): Use in terminal environments where you can install tools. Best for interactive exploration, one-off commands, and testing API calls during a session. Not suitable for persistent code.
- [Python SDK](https://docs.runloop.ai/docs/tools/sdks): Use when writing code that needs to persist beyond a single execution and your runtime is Python. Recommended for production agent workflows.
- [TypeScript SDK](https://docs.runloop.ai/docs/tools/sdks): Use when writing persistent code in a TypeScript or Node.js environment. Recommended for production agent workflows.
- [REST API](https://docs.runloop.ai/openapi-specs/stainless-processed-openapi.json): Use when integrating Runloop in environments where neither the CLI nor the SDKs (Python or TypeScript) are available. Requires constructing HTTP requests manually and handling authentication by including an `Authorization: Bearer $RUNLOOP_API_KEY` header in your requests.
- [MCP Server](https://docs.runloop.ai/docs/tools/ai-tools): Use when operating inside an AI tool (e.g. Claude, Cursor) that supports Model Context Protocol. Exposes Runloop operations as tool calls.

## SDKs and Client Libraries

- [Python SDK](https://github.com/runloopai/api-client-python): `pip install runloop-api-client` — [docs](https://docs.runloop.ai/docs/tools/sdks)
- [TypeScript SDK](https://github.com/runloopai/api-client-ts): `npm install @runloop/api-client` — [docs](https://docs.runloop.ai/docs/tools/sdks)
- [Runloop CLI](https://docs.runloop.ai/docs/tools/rl-cli): `rl-cli` — interactive API exploration and testing
- [API Reference](https://docs.runloop.ai/api-reference): direct REST API access
- [MCP Server / AI Tools](https://docs.runloop.ai/docs/tools/ai-tools): Model Context Protocol integration
- [Python Cursor Rules](https://docs.runloop.ai/static/files/runloop-python-client.mdc): `.mdc` rule file for Cursor IDE with the Python SDK
- [TypeScript Cursor Rules](https://docs.runloop.ai/static/files/runloop-typescript-client.mdc): `.mdc` rule file for Cursor IDE with the TypeScript SDK
- [GitHub Actions](https://docs.runloop.ai/docs/devboxes/agents/deploying-with-github-actions): CI/CD for agent deployment and benchmarking
---
## Documentation Index

## Overview

- [What is Runloop?](https://docs.runloop.ai/docs/overview/what-is-runloop) — Runloop: Sandbox Tools for AI Agent Workflows
- [Runloop Features](https://docs.runloop.ai/docs/overview/runloop-features) — Summary of Key Runloop Platform Features
- [Quickstart](https://docs.runloop.ai/docs/tutorials/quickstart) — Create your first Runloop Devbox in under a minute.
- [SDKs](https://docs.runloop.ai/docs/tools/sdks) — Use the Runloop SDKs to interact with the Runloop API.

## Tutorials

- [Tutorials](https://docs.runloop.ai/docs/tutorials/overview) — Step-by-step guides for common Runloop workflows
- [Running Agents on Sandboxes](https://docs.runloop.ai/docs/tutorials/running-agents-on-sandboxes) — Empower your agents to run code inside a devbox.
- [OpenAI Agents SDK + Runloop](https://docs.runloop.ai/docs/tutorials/openai-agentssdk-runloop) — Integrate Runloop cloud sandboxes with the OpenAI Agents SDK for secure, stateful AI agent execution.
- [OpenCode on Runloop](https://docs.runloop.ai/docs/tutorials/opencode-runloop) — Run OpenCode in secure Runloop devboxes with a fast blueprint workflow.
- [Browserbase on Runloop](https://docs.runloop.ai/docs/tutorials/browserbase-runloop) — Run browser agents from Runloop devboxes with Browserbase-managed browsers, connecting Playwright over CDP without installing Chromium in the devbox.
- [Kernel on Runloop](https://docs.runloop.ai/docs/tutorials/kernel-runloop) — Run browser agents from Runloop devboxes with Kernel-managed browsers, without installing Chromium or opening CDP from the devbox.
- [Axon + ACP with OpenCode](https://docs.runloop.ai/docs/tutorials/axon-acp-broker) — End-to-end example: create an Axon, attach Broker with the ACP protocol, and stream OpenCode output.

## Cookbooks

- [Share a Live Preview](https://docs.runloop.ai/docs/tutorials/running-agents-on-sandboxes/share-live-preview) — Start your app and share a live preview link in pull requests using devbox tunnels.
- [Suspend and Resume Workflow](https://docs.runloop.ai/docs/tutorials/running-agents-on-sandboxes/suspend-resume-workflow) — Suspend your devbox to preserve state, wait for PR feedback, and resume to continue working iteratively.
- [Turn-Based Interaction with Agent](https://docs.runloop.ai/docs/tutorials/running-agents-on-sandboxes/turn-based-interaction) — Create a turn-based workflow where the agent updates a GitHub PR with progress and responds to PR comments as prompts.

## Tools

- [Runloop Dashboard](https://docs.runloop.ai/docs/tools/dashboard) — Manage, monitor, and optimize your AI-powered coding environments with the Runloop Dashboard.
- [Runloop CLI](https://docs.runloop.ai/docs/tools/rl-cli) — Explore, experiment with, and test the Runloop API using the Runloop CLI.

## AI Integration

- [Support for AI tools](https://docs.runloop.ai/docs/tools/ai-tools) — Add context about the Runloop API to your LLMs
- [Cursor Rules](https://docs.runloop.ai/docs/tools/cursor-files) — Download .mdc rule files for Cursor IDE integration with the Runloop Python and TypeScript SDKs

## Components

- [Network Policies](https://docs.runloop.ai/docs/network-policies) — Control egress network access for your Devboxes

## Devboxes

- [Devbox Overview](https://docs.runloop.ai/docs/devboxes/overview) — Devbox: the Runloop Sandbox Environment
- [The Devbox Lifecycle](https://docs.runloop.ai/docs/devboxes/lifecycle) — Devbox state machine: Provisioning → Initializing → Running → Suspending → Suspended → Resuming → Shutdown / Failure. Key methods: suspend(), resume(), await_suspended() / awaitSuspended(), await_running() / awaitRunning(). Gotchas: only disk state survives suspend (in-memory is lost); background processes must be restarted after resume; suspended devboxes still incur storage charges.
- [Execute Commands on a Devbox](https://docs.runloop.ai/docs/devboxes/execute-commands) — Run commands via devbox.cmd.exec() (blocks, returns exit_code / stdout / stderr) or exec_async() / execAsync() (returns immediately with an Execution handle to check status, stream output, or kill). Both support streaming callbacks: stdout=, stderr=, output=. Gotcha: each exec() spawns an isolated shell — env vars and CWD do not persist between calls; use named shells for stateful sessions.
- [Execution Logs](https://docs.runloop.ai/docs/devboxes/execution-logs) — Stream logs in real-time or retrieve logs from completed executions
- [Named Shells](https://docs.runloop.ai/docs/devboxes/named-shells) — Stateful shell sessions via devbox.shell("name") → shell.exec(). Calling devbox.shell() with the same name reconnects to the live session, preserving env vars, CWD, and running processes. Commands queue sequentially within a session. Gotcha: two SDK clients using the same session name share one underlying shell.
- [PTY Sessions](https://docs.runloop.ai/docs/devboxes/pty) — Interactive pseudo-terminal via pty.connect(session_name=) returning a connect_url WebSocket endpoint. Terminal size: cols/rows params (default 80×24). Control via pty.control(): actions are resize (cols, rows), signal (e.g. SIGINT, SIGWINCH), close. Idle retention: idle_ttl_seconds. Gotchas: only one WebSocket attach at a time (second is rejected HTTP 400); disconnecting WebSocket does not terminate the session.
- [Read and Write Files on a Devbox](https://docs.runloop.ai/docs/devboxes/files) — Give your AI agent access to modify and interact with files on your devbox.
- [Devbox Snapshots](https://docs.runloop.ai/docs/devboxes/snapshots) — Save devbox disk state with snapshot_disk() / snapshotDisk() (synchronous) or snapshot_disk_async() / snapshotDiskAsync() + await_completion() / awaitCompletion() (async). Create a new devbox from a snapshot via snapshot.create_devbox() / createDevbox(). List with runloop.snapshot.list(devbox_id=). Gotcha: snapshots persist and accrue storage charges until explicitly deleted with snapshot.delete().
- [Devbox Lifetime Management](https://docs.runloop.ai/docs/devboxes/start-stop) — Configure devbox TTL, max lifetime (`keep_alive_time_seconds`), and idle-triggered shutdown or suspend (`lifecycle.after_idle` with `idle_time_seconds` and `on_idle: "shutdown" | "suspend"`). Gotcha: use `keep_alive_time_seconds` OR `lifecycle.after_idle`, never both — mixed configs are unsupported and behavior is undefined.
- [Configuring Devbox Instance Sizes](https://docs.runloop.ai/docs/devboxes/configuration/sizes) — Configure your Devboxes using predefined sizes
- [Configuring your devbox architecture](https://docs.runloop.ai/docs/devboxes/configuration/devbox-architecture) — Configuring the architecture on launched devboxes
- [Managing Account Secrets](https://docs.runloop.ai/docs/devboxes/configuration/account-secrets) — Store API keys at the account level via runloop.api.secrets.create() / list() / update() / delete(). Inject into a devbox at creation with the secrets parameter using the mapping {"ENV_VAR_NAME": "SECRET_NAME"} — key is the env var name inside the devbox, value is the account secret name. Secrets are injected as environment variables, not files.
- [Agent Gateways](https://docs.runloop.ai/docs/devboxes/agent-gateways) — Proxy AI API calls through Runloop so agents never see raw credentials. Attach via the gateways parameter on devbox.create(); create configs with runloop.gateway_configs.create() specifying endpoint and auth_mechanism (type: "bearer", "header", or "basic" — for basic, store the secret as plain "user:pass"). Configs may also carry up to 8 custom_headers, each pairing a name with exactly one of secret (account secret name or sec_ id) or value (plaintext literal) — use secrets for credentials. Auto-sets $<PREFIX>_URL and $<PREFIX> env vars in the devbox (e.g. $ANTHROPIC_URL, $ANTHROPIC for Claude). Gateway tokens are bound to the devbox — leaking them cannot be reused elsewhere. Supported clients: Anthropic SDK, OpenAI SDK, Claude Code, Codex, OpenCode, Gemini CLI.
- [MCP Hub](https://docs.runloop.ai/docs/devboxes/mcp-hub) — Give your agents access to MCP tool servers without exposing credentials. Create configs with runloop.mcp_config.create() specifying endpoint and allowed_tools glob patterns; optional auth_mechanism (bearer default, header, basic) controls how the bound secret is sent upstream, and up to 8 custom_headers (secret-backed or literal) ride alongside it for servers like Datadog that need two credential headers. Attach via the mcp map on devbox.create() — each map key becomes the env var holding that server's opaque token, all sharing $RL_MCP_URL.
- [Open a Tunnel to a Service on a devbox](https://docs.runloop.ai/docs/devboxes/tunnels) — Expose devbox ports via enable_tunnel() / enableTunnel(); retrieve the URL with get_tunnel_url(port). auth_mode: "open" or "authenticated" (requires auth_token bearer header). Supports HTTP, WebSocket, and SSE. wake_on_http: automatically resumes a suspended devbox on incoming HTTP traffic. Gotchas: service must bind 0.0.0.0 not localhost; for WebSocket, add https://*.tunnel.runloop.ai to your app's allowed origins.
- [SSH Access](https://docs.runloop.ai/docs/devboxes/ssh) — Connect with rli devbox ssh <devbox-id>; file transfer via rli devbox scp / rsync; rli devbox ssh --config-only generates an SSH config entry for VSCode Remote SSH or JetBrains Gateway. Programmatic access: create_ssh_key() / createSshKey() returns url, ssh_private_key, ssh_user. Gotcha: 15-minute inactivity timeout — add ServerAliveInterval 60 to your SSH config.
- [Storage Objects](https://docs.runloop.ai/docs/storage-objects/overview) — Upload files with upload_from_file() / uploadFromFile() or upload_from_text() / uploadFromText(). Get a time-limited signed download URL via get_download_url(seconds_to_expire) / getDownloadUrl(). Mount into devboxes with type: "object_mount" (object_id, object_path params). Archive gotcha: .gz, .tar, .tgz, .tar.gz files auto-extract when mounted. Delete with storage_object.delete() — objects persist and accrue charges otherwise.

## Mounts

- [Mounts Overview](https://docs.runloop.ai/docs/devboxes/mounts/overview) — Attach resources via the mounts parameter on devbox.create(). Each mount requires a type discriminator: "code_mount", "object_mount", "file_mount", or "agent_mount". Gotcha: mounts can only be specified at creation time — they cannot be added to a running devbox.
- [Mount AI Agents](https://docs.runloop.ai/docs/devboxes/mounts/agent-mounts) — Mount pre-configured AI agents to your Devboxes
- [Mount a Code Repository on a Devbox](https://docs.runloop.ai/docs/devboxes/mounts/code-mounts) — Clone a GitHub repo into a devbox at creation with type: "code_mount", repo_name, and repo_owner. For private repos, pass token (GitHub PAT) — this also sets GH_TOKEN in the devbox, enabling the gh CLI for opening PRs. install_command runs after cloning (e.g. "npm install"). Repo is cloned to ~/<repo_name>.
- [Mount Storage Objects](https://docs.runloop.ai/docs/devboxes/mounts/object-mounts) — Mount files and data objects to your Devboxes
- [Mount Files Inline](https://docs.runloop.ai/docs/devboxes/mounts/file-mounts) — Inject file content directly into your Devbox at creation time

## Advanced Devbox Topics

- [Managing Devbox Metadata](https://docs.runloop.ai/docs/devboxes/configuration/metadata) — Effectively manage and organize large numbers of Devboxes using metadata
- [Running Docker on a Devbox](https://docs.runloop.ai/docs/devboxes/capabilities/docker-in-docker) — Run Docker on a Devbox (Docker-in-Docker)
- [Configuring your bash environment](https://docs.runloop.ai/docs/devboxes/configuration/bash-profile-environment-setup) — Configuring the bash environment on your devboxes
- [Configuring your devbox user profile](https://docs.runloop.ai/docs/devboxes/configuration/user-parameters) — Custom users for your devboxes

## Blueprints

- [Blueprints Overview](https://docs.runloop.ai/docs/devboxes/blueprints/overview) — Container image templates for fast devbox startup. Specify at creation with blueprint_name or blueprint_id on devbox.create(). Create programmatically via runloop.blueprint.create() or from a Dockerfile with rli blueprint from-dockerfile. Prebuilt images: runloop/universal-ubuntu-24.04-x86_64, runloop/starter-x86_64. Use launch_commands to pre-install tools at build time. Gotcha: background processes in launch_commands must redirect output (> /tmp/out.log 2>&1 &) or the devbox hangs in Initializing indefinitely.
- [Files and Build Context](https://docs.runloop.ai/docs/devboxes/blueprints/files-and-mounts) — Add files, code repositories, and build contexts to your Blueprints
- [Dockerfile Customization](https://docs.runloop.ai/docs/devboxes/blueprints/dockerfile-customization) — Create Blueprints using custom Dockerfiles, public registries, secrets, and composable blueprints
- [Network Policies for Blueprints](https://docs.runloop.ai/docs/devboxes/blueprints/network-policies) — Restrict network access during blueprint builds and for Devboxes created from blueprints
- [Blueprint Lifecycle](https://docs.runloop.ai/docs/devboxes/blueprints/lifecycle) — Manage blueprint launch parameters, deletion, and cleanup
- [Troubleshooting Blueprint Builds](https://docs.runloop.ai/docs/devboxes/configuration/troubleshooting/troubleshooting-blueprints) — Debug and fix your Blueprint builds in Runloop.

## Agents

- [Using the Agents API](https://docs.runloop.ai/docs/devboxes/agents/using-agents-api) — Create and manage agents on Runloop
- [Deploying Agents with GitHub Actions](https://docs.runloop.ai/docs/devboxes/agents/deploying-with-github-actions) — Automate agent deployment using the Runloop deploy-agent GitHub Action

## Axons

- [Axons](https://docs.runloop.ai/docs/axons/overview) — Persistent event streams for agent lifecycle management, state recovery, and turn-based interactions
- [Remote Agents SDK](https://docs.runloop.ai/docs/axons/sdk) — Build CLIs, apps, and integrations with the Remote Agents SDK for TypeScript
- [SQL Database](https://docs.runloop.ai/docs/axons/sql) — Private embedded SQLite database for structured state within an Axon

## Broker

- [Broker](https://docs.runloop.ai/docs/axons/broker) — Broker is the bridge between Axon event streams and agent processes running in Devboxes

## Protocols

- [ACP Protocol](https://docs.runloop.ai/docs/axons/broker/acp) — Use the Agent Client Protocol (ACP) to connect Broker to ACP-compatible agents like OpenCode and Goose
- [Claude JSON Protocol](https://docs.runloop.ai/docs/axons/broker/claude) — Use the Claude JSON protocol to connect Broker to Claude Code CLI

## Benchmarks & Evals

- [Overview of Benchmarks & Scenarios on Runloop](https://docs.runloop.ai/docs/benchmarks/overview) — Make your agent better and more reliable with Runloop's tools for benchmarking.
- [Orchestrated Benchmarks](https://docs.runloop.ai/docs/benchmarks/orchestrated-benchmarks) — Run benchmarks at cloud scale with a single CLI command.
- [Interactive Public Benchmarks](https://docs.runloop.ai/docs/benchmarks/public-benchmarks) — Run your agent against popular public benchmarks with full control over the execution process.
- [Build Custom Agent Benchmarks with Runloop](https://docs.runloop.ai/docs/benchmarks/custom-benchmarks) — Learn how to create and run custom benchmarks

## Advanced Benchmarks

- [Training Using Benchmarks](https://docs.runloop.ai/docs/benchmarks/training-using-benchmarks) — Use benchmarks and scenarios to measure and improve agent performance across a range of learning workflows.
- [Creating Scenarios](https://docs.runloop.ai/docs/benchmarks/creating-scenarios) — Learn how to create, configure, and run scenarios in Runloop.
- [Scorers](https://docs.runloop.ai/docs/benchmarks/custom-scorers) — Learn how to create and customize scoring functions.

## Debugging

- [Debugging Agents with rl-cli](https://docs.runloop.ai/docs/devboxes/configuration/troubleshooting/debugging-agent-output-with-ssh) — Securely connect to a remote Runloop Devbox using SSH for debugging

## API Reference

- [API Reference](https://docs.runloop.ai/api-reference) — Interactive reference for all Runloop REST API endpoints
- [OpenAPI Specification](https://docs.runloop.ai/openapi-specs/stainless-processed-openapi.json) — Raw OpenAPI spec (JSON)

## Changelog

- [Runloop Changelog](https://docs.runloop.ai/docs/overview/release-notes) — Latest updates and improvements to Runloop