Set up Runloop with an AI agent

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

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 — Core concepts, lifecycle, and SDK examples
• Blueprints Overview — Creating reusable environments
• Axons Overview — Event streams, Broker, and multi-turn workflows

---

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