# 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
- **[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.
- [OpenCode on Runloop](https://docs.runloop.ai/docs/tutorials/opencode-runloop) — Run OpenCode in secure Runloop devboxes with a fast blueprint workflow.
- [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) — Understand the stages of the Devbox lifecycle.
- [Execute Commands on a Devbox](https://docs.runloop.ai/docs/devboxes/execute-commands) — Run and execute code at scale
- [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) — Use stateful named shells to maintain environment and working directory across commands
- [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 Lifetime Management](https://docs.runloop.ai/docs/devboxes/start-stop) — Control devbox automatic shutdown and idle behaviors
- [Devbox Snapshots](https://docs.runloop.ai/docs/devboxes/snapshots) — Saved diskstates from existing for devboxes for re-use & branching
- [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) — Securely manage API keys, tokens, and other sensitive configuration data at the account level
- [Agent Gateways](https://docs.runloop.ai/docs/devboxes/agent-gateways) — Securely proxy API requests without exposing credentials to your agents
- [MCP Hub](https://docs.runloop.ai/docs/devboxes/mcp-hub) — Give your agents access to MCP tool servers without exposing credentials
- [Open a Tunnel to a Service on a devbox](https://docs.runloop.ai/docs/devboxes/tunnels) — Create a tunnel to access ports on your devbox
- [SSH Access](https://docs.runloop.ai/docs/devboxes/ssh) — Securely connect to your Devbox over SSH with end-to-end encryption
- [Storage Objects](https://docs.runloop.ai/docs/storage-objects/overview) — Store and manage files and data objects for integration with Devboxes and Blueprints

## Mounts

- [Mounts Overview](https://docs.runloop.ai/docs/devboxes/mounts/overview) — Mount code repositories, files, objects, and agents to your Devboxes
- [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) — Enable AI agents to work with full projects: access public and private repositories
- [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) — Template images for optimized Devbox startup
- [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) — Distributed event streams for sequencing, recording, and observing agent interactions
- [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