Skip to main content

​
Getting Started with Runloop

Runloop Devboxes are a secure and isolated environment for running AI-generated code. This tutorial gets you up and running with your first devbox in about 1 minute.
For your convenience, we have SDKs for Python and TypeScript. The Python SDK is available in both synchronous and async variants. We recommend using the async SDK for improved performance.
1

Create an API Key

Visit the Runloop signup page to create an account. Once your account is active, visit the Settings page on the Runloop Dashboard to create an API key.
2

Set Up Your Development Environment

Set up your Runloop API key as an environment variable. This allows the Runloop SDK to authenticate you and create your devbox.
export RUNLOOP_API_KEY=<your_runloop_api_key_here>
3

Install the client SDK

Install the Runloop client SDK for TypeScript or Python.
mkdir runloop-examples
cd runloop-examples
uv venv .runloop-venv
source .runloop-venv/bin/activate
uv pip install runloop_api_client
4

Create a Devbox and run a command

Now, let’s create a Devbox to use as our sandbox environment. Copy the script below to a file, e.g. testprog.py for Python or testprog.ts for TypeScript.
import asyncio
from runloop_api_client import AsyncRunloopSDK

# API Key is auto-loaded from "RUNLOOP_API_KEY" env var
runloop = AsyncRunloopSDK()

async def run_example():
  # create the devbox and wait for it to be ready
  devbox = await runloop.devbox.create()
  print(f'Created Runloop Devbox: {devbox.id}')

  # Execute a command and wait for it to complete
  result = await devbox.cmd.exec(command="echo 'Runloop!!'")
  print(await result.stdout())  # Runloop!!
  print(f'Exit code: {result.exit_code}')  # 0

  # Clean up the Devbox
  await devbox.shutdown()

asyncio.run(run_example())
The runloop SDK object is your main entry point for interacting with the Runloop API.
5

Run the example

Creating and starting a Devbox takes just seconds, and allows you to safely run LLM-generated code, execute tests, etc. The example code above
  • creates and launches a devbox
  • runs a simple command
  • shuts the devbox down when it is done
… in just a few seconds!Try running it like this:
uv run ./testprog.py
Our starter image is what starts when you start a devbox. You get the following packages available to your devbox:Core tools: curl, ca-certificates, jq, sudo, git
Extras: dnsutils, iputils-ping, less, vim, wget, rsync, gh
Python stack: Python 3.12, pip, uv
Node stack: Node 22.15.0, npm, Yarn 1.22.22 via corepack

​
Using Runloop Code Examples

The other tutorials and code examples on this site assume you have set up your environment as indicated above. We also use the same variable names throughout, so if you want to try other code snippets, just paste them into your run_example function and try them out!

​
Tutorials

A collection of tutorials showing you how to use Runloop. We’re constantly expanding this collection, so check back often!

Running Agents on Sandboxes

Create an AI agent, set up a devbox with code and agent mounts, and modify code in a demo app.

Share a Live Preview

Start your app and share a live preview link in pull requests using devbox tunnels.

Suspend and Resume Workflow

Preserve devbox state, wait for PR feedback, and resume to continue working iteratively.

Turn-Based Interaction

Create a workflow where the agent posts status updates and responds to PR comments as prompts.

​
Learn More

By default, a Devbox’s disk state is deleted when it is shut down. If your application needs persistent state across boots, you can configure your devbox for automatic suspend and resume.
As you go further with Devboxes, you will probably want to customize the Devbox environment to include the code and tools you use most often. You can use Runloop blueprints and snapshots to build images specific to your needs and avoid re-loading dependencies on startup.