---
name: runloopai
description: Use when building, deploying, and managing AI agents that need
  isolated sandboxed environments to execute code, run tests, interact with
  repositories, and coordinate multi-turn workflows. Reach for this skill when
  agents need to execute arbitrary code safely, manage persistent state,
  coordinate events, or integrate with external systems.
metadata:
  mintlify-proj: runloopai
  version: "1.0"
---

# Runloop Skill

## Product Summary

Runloop is a platform for building and deploying AI agents with managed sandboxed execution environments (Devboxes), persistent event streams (Axons), and reusable environment templates (Blueprints). Agents use the Runloop SDK (Python or TypeScript) to create Devboxes, execute commands, manage files, and coordinate workflows. Key entry points: Python SDK (`runloop_api_client`), TypeScript SDK (`@runloop/api-client`), CLI (`rli`), and REST API at `https://api.runloop.ai/v1`. Comprehensive documentation at https://docs.runloop.ai.

## When to Use

Reach for Runloop when:
- An agent needs to execute untrusted or AI-generated code safely in isolation
- You're building multi-turn agent workflows that need persistent state and event ordering
- Agents must interact with Git repositories, run tests, or perform file operations
- You need to coordinate work across multiple agents or external systems via event streams
- You're prototyping quickly and want zero infrastructure setup
- You need to suspend/resume agent work to save costs while preserving disk state
- Agents require access to external APIs via secure proxies (Agent Gateways) or MCP tools

Do not use Runloop for: simple chatbots without code execution, synchronous request-response patterns that don't need persistence, or workloads that don't require isolation.

## Quick Reference

### SDK Installation & Setup

| Task | Command |
|------|---------|
| Install Python SDK | `pip install runloop-api-client` |
| Install TypeScript SDK | `npm install @runloop/api-client` |
| Install CLI | `npm install -g @runloop/rl-cli` |
| Set API key | `export RUNLOOP_API_KEY=your_key` |
| Get API key | Visit https://platform.runloop.ai/settings#api-keys |

### Core Devbox Operations

| Operation | Python | TypeScript |
|-----------|--------|-----------|
| Create devbox | `await runloop.devbox.create()` | `await runloop.devbox.create()` |
| Execute command | `await devbox.cmd.exec("command")` | `await devbox.cmd.exec("command")` |
| Read file | `await devbox.file.read("/path/file")` | `await devbox.file.read("/path/file")` |
| Write file | `await devbox.file.write("/path/file", content)` | `await devbox.file.write("/path/file", content)` |
| Shutdown | `await devbox.shutdown()` | `await devbox.shutdown()` |
| Suspend | `await devbox.suspend()` | `await devbox.suspend()` |
| Resume | `await devbox.resume()` | `await devbox.resume()` |

### CLI Quick Commands

```bash
rli devbox create --name my-box                    # Create devbox
rli devbox list                                    # List all devboxes
rli devbox exec <id> "command"                     # Run command
rli devbox ssh <id>                                # SSH into devbox
rli devbox suspend <id>                            # Suspend devbox
rli devbox resume <id>                             # Resume devbox
rli blueprint create --name my-bp                  # Create blueprint
rli snapshot create <devbox-id>                    # Create snapshot
rli secret create <name>                           # Create account secret
```

### Devbox Sizes

| Size | vCPU | RAM | Disk | Use Case |
|------|------|-----|------|----------|
| X_SMALL | 0.5 | 1 GB | 4 GB | Quick tests, minimal workloads |
| SMALL | 1 | 2 GB | 4 GB | Default, most agents |
| MEDIUM | 2 | 4 GB | 8 GB | Moderate builds, testing |
| LARGE | 2 | 8 GB | 16 GB | Heavy builds, Docker |
| X_LARGE | 4 | 16 GB | 16 GB | Complex workflows |
| XX_LARGE | 8 | 32 GB | 16 GB | Parallel builds, large datasets |

### Mount Types

| Mount Type | Best For | Limit | Example |
|-----------|----------|-------|---------|
| Code Mount | Git repos (public/private) | Unlimited | Clone repo, run agent against codebase |
| File Mount | Config, scripts, env files | 12 KB per file, 128 KB total | Inject `.env`, shell scripts |
| Object Mount | Large files, archives, datasets | Unlimited | Upload 100 MB dataset, binary tools |
| Agent Mount | Pre-configured AI agents | Varies | Mount agent from Git, npm, PyPI |

## Decision Guidance

### When to Use Snapshots vs Blueprints

| Scenario | Use Snapshots | Use Blueprints |
|----------|---------------|----------------|
| Save exact disk state of a running devbox | ✓ | |
| Reuse across team, version control setup | | ✓ |
| Quick rollback to known good state | ✓ | |
| Pre-install tools for all future devboxes | | ✓ |
| Capture build cache, dependencies | ✓ | |
| Define standard dev environment | | ✓ |
| One-off experiment or branch | ✓ | |

### When to Use Suspend/Resume vs Shutdown

| Scenario | Suspend/Resume | Shutdown |
|----------|----------------|----------|
| Waiting for PR feedback, human input | ✓ | |
| Preserving in-progress work | ✓ | |
| Saving on compute costs (storage still charged) | ✓ | |
| Cleaning up completely, no future use | | ✓ |
| Long-running agent pausing between turns | ✓ | |
| Temporary experiment, no state needed | | ✓ |

### When to Use Axons vs Direct Devbox Calls

| Scenario | Use Axons | Direct Devbox |
|----------|-----------|---------------|
| Multi-turn agent conversations | ✓ | |
| Coordinating multiple agents | ✓ | |
| Webhook fan-in from external systems | ✓ | |
| Replay and audit trail required | ✓ | |
| Simple one-off code execution | | ✓ |
| Agent needs to suspend/resume on idle | ✓ | |
| Stateless, fire-and-forget tasks | | ✓ |

## Workflow

### Typical Agent Execution Flow

1. **Set up authentication**
   - Create API key in Runloop Dashboard
   - Export `RUNLOOP_API_KEY` environment variable
   - Verify with `rli devbox list` (should return empty or existing devboxes)

2. **Prepare environment (optional)**
   - Create a Blueprint if agents need pre-installed tools: `rli blueprint create --name my-env --system-setup-commands "apt install -y jq"`
   - Or use a prebuilt blueprint like `runloop/universal-ubuntu-24.04-x86_64`
   - Wait for blueprint build to complete: `rli blueprint get my-env`

3. **Create and configure devbox**
   - Create devbox from blueprint or default image: `await runloop.devbox.create({ blueprint_name: "my-env" })`
   - Mount code if needed: pass `code_mounts` with Git repo URL and auth token
   - Inject secrets: pass `secrets` mapping to account-level secrets
   - Set resource size: `resource_size_request: "MEDIUM"`

4. **Execute agent work**
   - Run commands: `await devbox.cmd.exec("python agent.py")`
   - Read/write files: `await devbox.file.read("/path/file")`
   - Check logs: `await devbox.get_logs()` or `rli devbox logs <id>`
   - Use stateful shells for multi-step workflows: `shell_name: "main"`

5. **Manage lifecycle**
   - For iterative work: suspend devbox `await devbox.suspend()`, resume later `await devbox.resume()`
   - For one-off tasks: shutdown immediately `await devbox.shutdown()`
   - For reuse: create snapshot `await devbox.snapshot_disk()`, launch new devbox from it

6. **Coordinate multi-turn workflows (with Axons)**
   - Create Axon: `await runloop.axon.create({ name: "my-channel" })`
   - Publish events: `await axon.publish({ source: "app", event_type: "user.message", origin: "USER_EVENT", payload: JSON.stringify({...}) })`
   - Subscribe to stream: `for await (const event of await axon.subscribeSse()) { ... }`
   - Mount Broker to devbox to auto-forward events to agent

### Debugging Workflow

1. Check devbox status: `rli devbox get <id>` or `await devbox.get_info()`
2. Review logs: `rli devbox logs <id>` (retained 28 days)
3. SSH into devbox: `rli devbox ssh <id>` for interactive inspection
4. Check execution status: `await devbox.get_execution_status(execution_id)` for async commands
5. Review Blueprint build logs if creation failed: `rli blueprint logs <blueprint-id>`

## Common Gotchas

- **Background processes block devbox startup**: If `launch_commands` start a daemon without redirecting output, devbox stays in `initializing` state. Always redirect: `my-server start > /tmp/server.log 2>&1 &`

- **Suspend preserves disk, not memory**: Running processes are lost on suspend. Serialize state to disk before suspending (write files, update database).

- **Suspended devboxes still incur storage charges**: Shutdown explicitly when done to avoid surprise costs.

- **Snapshots are immutable**: Once created, snapshots cannot be modified. Delete old snapshots to manage storage.

- **API key scope matters**: For CI/CD, use restricted keys scoped to only needed resources (e.g., `Agents: write, Objects: write`). Full-access keys are fine for local development.

- **File mounts have size limits**: Max 12 KB per file, 128 KB total. Use Object Mounts for larger files.

- **Code mounts require auth tokens for private repos**: Pass `auth_token` with sufficient permissions (e.g., GitHub PAT with `repo` scope).

- **Execution logs expire after 28 days**: Download or archive logs before retention window closes.

- **Blueprint build context is temporary**: Build context objects expire after 1 hour by default. Rebuild if needed.

- **Devbox IDs are stable across suspend/resume**: SSH keys and network configuration persist, but in-memory state does not.

- **Axon events are immutable and limited to 10 GB**: Cannot delete or modify events. Plan for event retention and archival.

- **Missing RUNLOOP_API_KEY causes 401 errors**: Check for trailing spaces, quotes, or expired keys. Regenerate in Dashboard if needed.

## Verification Checklist

Before submitting agent code or workflow:

- [ ] Devbox reaches `running` state (check `rli devbox get <id>` or `await devbox.get_info()`)
- [ ] Commands execute without errors (check exit code and stderr in logs)
- [ ] Files are written to expected paths (verify with `rli devbox read <id> --remote /path/file`)
- [ ] Mounts are accessible (test with `ls` or `cat` commands)
- [ ] Secrets are injected as environment variables (check with `env | grep SECRET_NAME`)
- [ ] Snapshots complete successfully (status should be `ready`, not `failed`)
- [ ] Blueprints build without errors (check `rli blueprint logs <id>` for build failures)
- [ ] Axon events publish with correct sequence numbers (verify via `await axon.listEvents()`)
- [ ] Suspend/resume preserves disk state (create file, suspend, resume, verify file exists)
- [ ] Logs are accessible and not truncated (check `stdout_truncated` and `stderr_truncated` flags)

## Resources

**Comprehensive navigation**: https://docs.runloop.ai/llms.txt

**Critical documentation pages**:
- [Devbox Overview](https://docs.runloop.ai/docs/devboxes/overview) — Core concepts, lifecycle, and SDK examples
- [Blueprints Overview](https://docs.runloop.ai/docs/devboxes/blueprints/overview) — Creating reusable environments
- [Axons Overview](https://docs.runloop.ai/docs/axons/overview) — Event streams, Broker, and multi-turn workflows

---

> For additional documentation and navigation, see: https://docs.runloop.ai/llms.txt