> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create your first Runloop Devbox in under a minute.

## 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.

> [!NOTE]
>
> For your convenience, we have SDKs for [Python](https://runloopai.github.io/api-client-python/sdk/async/index.html)
> and [TypeScript](https://runloopai.github.io/api-client-ts/stable/). The Python SDK is available in both
> [synchronous](https://runloopai.github.io/api-client-python/sdk/sync/index.html) and
> [async](https://runloopai.github.io/api-client-python/sdk/async/index.html)
> variants. We recommend using the async SDK for improved performance.

**1. Create an API Key**

Visit the [Runloop signup
page](https://platform.runloop.ai/auth/register) to create an
account. Once your account is active, visit the
[Settings](https://platform.runloop.ai/settings#api-keys) page on
the [Runloop Dashboard](https://platform.runloop.ai) to
create an API key. For local development, a secret key with full access
is fine. For CI/CD or integrations with limited needs, consider a
[restricted key](https://platform.runloop.ai/settings#restricted-keys) instead.

**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.

```bash theme={null}
export RUNLOOP_API_KEY=<your_runloop_api_key_here>
```

**3. Install the client SDK**

Install the Runloop client SDK for TypeScript or Python.

```bash Python theme={null}
mkdir runloop-examples
cd runloop-examples
uv venv .runloop-venv
source .runloop-venv/bin/activate
uv pip install runloop_api_client
```

```bash TypeScript theme={null}
mkdir runloop-examples
cd runloop-examples
npm 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.

```python Python theme={null}
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())
```

```typescript TypeScript theme={null}
import { RunloopSDK } from '@runloop/api-client';

// API Key is auto-loaded from "RUNLOOP_API_KEY" env var
const runloop = new RunloopSDK();

async function runExample() {
  // Create a new devbox and wait for it to be ready
  const devbox = await runloop.devbox.create();
  console.log(`Created Runloop Devbox: ${devbox.id}`);

  // Execute a command and wait for it to complete
  const result = await devbox.cmd.exec("echo 'Runloop!!'");
  console.log('Output:', await result.stdout()); // "Runloop!!"
  console.log('Exit code:', result.exitCode); // 0

  // Clean up the Devbox
  await devbox.shutdown();
}

runExample();
```

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:

```bash Python theme={null}
uv run ./testprog.py
```

```bash TypeScript theme={null}
npx ts-node ./testprog.ts
```

> [!NOTE]
>
> The starter image is used when you start a devbox without specifying an image, and as the default base when you build a blueprint without providing Dockerfile content. It includes:
>
> * **Core tools:** jq, sudo
> * **Extras:** dnsutils, iputils-ping, less, vim, 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!

> [card] [Running Agents on Sandboxes](https://docs.runloop.ai/docs/tutorials/running-agents-on-sandboxes.md)
>
> Create an AI agent, set up a devbox with code and agent mounts, and modify code in a demo app.

> [card] [Share a Live Preview](https://docs.runloop.ai/docs/tutorials/running-agents-on-sandboxes/share-live-preview.md)
>
> Start your app and share a live preview link in pull requests using devbox tunnels.

> [card] [Suspend and Resume Workflow](https://docs.runloop.ai/docs/tutorials/running-agents-on-sandboxes/suspend-resume-workflow.md)
>
> Preserve devbox state, wait for PR feedback, and resume to continue working iteratively.

> [card] [Turn-Based Interaction](https://docs.runloop.ai/docs/tutorials/running-agents-on-sandboxes/turn-based-interaction.md)
>
> Create a workflow where the agent posts status updates and responds to PR comments as prompts.

## Learn More

> [!NOTE]
>
> 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](https://docs.runloop.ai/docs/devboxes/lifecycle.md#suspending-and-resuming-devboxes-to-save-disk-state).

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](https://docs.runloop.ai/docs/devboxes/blueprints.md) and
[snapshots](https://docs.runloop.ai/docs/devboxes/snapshots.md) to build images specific to your
needs and avoid re-loading dependencies on startup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.