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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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>
    ```
  </Step>

  <Step title="Install the client SDK">
    Install the Runloop client SDK for TypeScript or Python.

    <CodeGroup>
      ```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
      ```
    </CodeGroup>
  </Step>

  <Step title="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.

    <CodeGroup>
      ```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();
      ```
    </CodeGroup>

    The `runloop` SDK object is your main entry point for interacting with the Runloop API.
  </Step>

  <Step title="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:

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

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

    <Note title="Starter image">
      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
    </Note>
  </Step>
</Steps>

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

<Columns cols={2}>
  <Card title="Running Agents on Sandboxes" icon="robot" href="/docs/tutorials/running-agents-on-sandboxes">
    Create an AI agent, set up a devbox with code and agent mounts, and modify code in a demo app.
  </Card>

  <Card title="Share a Live Preview" icon="globe" href="/docs/tutorials/running-agents-on-sandboxes/share-live-preview">
    Start your app and share a live preview link in pull requests using devbox tunnels.
  </Card>

  <Card title="Suspend and Resume Workflow" icon="pause" href="/docs/tutorials/running-agents-on-sandboxes/suspend-resume-workflow">
    Preserve devbox state, wait for PR feedback, and resume to continue working iteratively.
  </Card>

  <Card title="Turn-Based Interaction" icon="comments" href="/docs/tutorials/running-agents-on-sandboxes/turn-based-interaction">
    Create a workflow where the agent posts status updates and responds to PR comments as prompts.
  </Card>
</Columns>

## Learn More

{/* TODO: the link below is to a discussion of manual suspend/resume, but does not mention auto suspend on idle. */}

<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](/docs/devboxes/lifecycle#suspending-and-resuming-devboxes-to-save-disk-state).
</Note>

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