Runloop API Client

Warnings

• deprecated The `blueprints.preview()` method has been deprecated.
  Fix: Review the latest documentation for blueprint management for alternative or updated methods. It is listed as deprecated in API specs.
• breaking Migration from an older 'API Client' to the current `RunloopSDK` structure may require updating import paths and method calls. For instance, `runloop.secrets` has moved to `runloopSDK.api.secrets`.
  Fix: Update imports from `Runloop` to `RunloopSDK` or `AsyncRunloopSDK` and adjust method calls to use the `sdk.api` property for direct REST API access or the object-oriented interfaces (e.g., `sdk.devbox`).
• gotcha Authentication primarily relies on the `RUNLOOP_API_KEY` environment variable. If not set, the client may fail to authenticate or you'll need to pass the `bearer_token` explicitly.
  Fix: Always ensure the `RUNLOOP_API_KEY` environment variable is set before initializing the client, or explicitly pass `bearer_token` during client instantiation: `RunloopSDK(bearer_token="your_key")`.
• gotcha Devboxes are persistent resources. Failing to explicitly shut down a `Devbox` using `await devbox.shutdown()` (or using a context manager with `with runloop.devbox.create(...)`) can lead to lingering resources and unexpected costs.
  Fix: Always call `await devbox.shutdown()` or use a `with` statement with `runloop.devbox.create()` for proper resource cleanup.

Install

• pip install runloop_api_client Install stable version

Imports

• RunloopSDK

  from runloop_api_client import RunloopSDK

  Use this for the higher-level, object-oriented synchronous API client.
• AsyncRunloopSDK

  from runloop_api_client import AsyncRunloopSDK

  Use this for the higher-level, object-oriented asynchronous API client, recommended for performance.
• Runloop

  from runloop_api_client import Runloop

  Use this for direct access to the lower-level REST API client. The SDK interfaces (RunloopSDK/AsyncRunloopSDK) are generally preferred.

Quickstart

This quickstart demonstrates how to initialize the `AsyncRunloopSDK` client, create a Devbox, execute a command within it, and then properly shut down the Devbox. Ensure your `RUNLOOP_API_KEY` is set as an environment variable for authentication.

import asyncio
import os
from runloop_api_client import AsyncRunloopSDK

async def run_example():
    # API Key is auto-loaded from "RUNLOOP_API_KEY" env var by default.
    # Ensure RUNLOOP_API_KEY is set in your environment (e.g., export RUNLOOP_API_KEY="your_api_key_here")
    # or pass it explicitly: AsyncRunloopSDK(bearer_token="your_api_key_here")
    runloop = AsyncRunloopSDK(bearer_token=os.environ.get('RUNLOOP_API_KEY', ''))

    devbox = None # Initialize devbox to None for finally block
    try:
        # Create a 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 'Hello from Runloop!!'")
        print(f'Output: {await result.stdout()}')
        print(f'Exit code: {result.exit_code}')

    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        if devbox:
            print(f'Shutting down Devbox: {devbox.id}')
            await devbox.shutdown()

if __name__ == "__main__":
    # Ensure the RUNLOOP_API_KEY environment variable is set.
    if not os.environ.get('RUNLOOP_API_KEY'):
        print("Warning: RUNLOOP_API_KEY environment variable is not set.")
        print("Please set it (e.g., export RUNLOOP_API_KEY='your_api_key_here') before running.")
    asyncio.run(run_example())