Cursor Rules

You are working with runloop_api_client, a Python SDK for deploying and managing remote devboxes for AI agents. Use this guide to properly interact with the SDK.

Devbox Overview

A Devbox is a virtual development environment designed for running AI-generated or arbitrary code in an isolated sandbox. It provides configurable compute resources, supports execution of shell commands, and can be managed via API.

Each Devbox has a unique ID, a status (e.g., running, suspended, or shutdown), and metadata for user-defined settings. It includes launch parameters for customizing resource size, execution behavior, and available ports.

Key attributes:

ID (string, required) – Unique identifier of the Devbox.
Status (enum, required) – Current state of the Devbox (e.g., provisioning, running, shutdown).
Create time (integer, required) – Timestamp (ms) when the Devbox was created.
Launch parameters (object, required) – Includes startup commands, resource configuration, idle timeout, and network settings.
Capabilities (list, required) – Defines supported tools such as computer usage APIs, browser usage, and language servers.
Blueprint/Snapshot ID (string, optional) – Identifier if created from a predefined Blueprint or Snapshot.
Failure/Shutdown reason (enum, optional) – Reason for termination if applicable (e.g., out of memory, idle shutdown).
Devboxes can be started, suspended, resumed, or shut down, and they support file operations, shell command execution, and network tunneling.

CORE SDK USAGE:

Initialize client:
from runloop_api_client import Runloop
client = Runloop(api_key="YOUR_API_KEY")
DEVBOX LIFECYCLE:

Create a new Devbox:
devbox_view = client.devboxes.create(
    name="devbox_name",
    blueprint_id="blueprint_id",
    snapshot_id="snapshot_id",
    launch_parameters={}
)
client.devboxes.await_running(browser.devbox.id)

Retrieve an existing Devbox:
    devbox_view = client.devboxes.retrieve(id="devbox_id")
List Devboxes:
    page = client.devboxes.list(status="running", limit=10)
Suspend a Devbox:
    devbox_view = client.devboxes.suspend(id="devbox_id")
Resume a Devbox:
    devbox_view = client.devboxes.resume(id="devbox_id")
Shutdown a Devbox:
    devbox_view = client.devboxes.shutdown(id="devbox_id")
Keep a Devbox alive:
    response = client.devboxes.keep_alive(id="devbox_id")

DEVBOX FILE OPERATIONS:

Write file contents:
    response = client.devboxes.write_file_contents(
        id="devbox_id",
        file_path="path/to/file.txt",
        contents="Hello, world!"
    )
Read file contents:
    response = client.devboxes.read_file_contents(
        id="devbox_id",
        file_path="path/to/file.txt"
    )
Upload a file:
    response = client.devboxes.upload_file(id="devbox_id", path="path/to/upload")
Download a file:
    response = client.devboxes.download_file(id="devbox_id", path="path/to/file.txt")
    content = response.read()

DEVBOX EXECUTION:

Execute command synchronously:
    execution_detail = client.devboxes.execute_sync(id="devbox_id", command="ls -la")
Execute command asynchronously:
    async_execution = client.devboxes.execute_async(id="devbox_id", command="ls -la")
Retrieve execution status:
    execution_status = client.devboxes.executions.retrieve(
        devbox_id="devbox_id",
        execution_id="execution_id"
    )

DEVBOX NETWORKING:

Create a tunnel:
    tunnel = client.devboxes.create_tunnel(id="devbox_id", port=8080)
Remove a tunnel:
    tunnel = client.devboxes.remove_tunnel(id="devbox_id", port=8080)
Create an SSH key:
    ssh_key = client.devboxes.create_ssh_key(id="devbox_id")

DEVBOX SNAPSHOT MANAGEMENT:

List disk snapshots:
    page = client.devboxes.list_disk_snapshots(devbox_id="devbox_id", limit=10)
Create a disk snapshot:
    snapshot = client.devboxes.snapshot_disk(id="devbox_id", name="snapshot_name")
Delete a disk snapshot:
    response = client.devboxes.delete_disk_snapshot(id="snapshot_id")

DEVBOX LOGGING:

Retrieve logs:
    logs = client.devboxes.logs.list(id="devbox_id", execution_id="execution_id")

REPOSITORY OBJECT

  A Repository in Runloop represents a connection to a remote repository and facilitates its automated analysis. This enables users to manage and inspect repositories efficiently.

  ATTRIBUTES
  - id (string, required) - Unique identifier of the Repository.
  - name (string, required) - The name of the Repository.
  - owner (string, required) - The account owner associated with the Repository.
  - status (enum<string>, required) - The current state of the Repository.  
    Available options: `pending`, `failure`, `active`.
  - failure_reason (string | null, optional) - The reason for failure, if the repository has a `failure` status.

  Repositories can be created, retrieved, listed, and deleted using the Runloop API.


REPOSITORY OPERATIONS


  List repositories:
      repositories = client.repositories.list(limit=10)
  Create a repository connection:
      repository = client.repositories.create(name="repo_name", owner="repo_owner")
  Retrieve repository details:
      repository = client.repositories.retrieve(id="repo_id")
  Delete a repository:
      response = client.repositories.delete(id="repo_id")
  List repository versions:
      repo_versions = client.repositories.versions(id="repo_id")

  Using Blueprints in Runloop SDK

  Blueprints provide a way to create customized starting points for Devboxes, caching environment setups to improve boot times. They allow pre-configured development environments to be reused efficiently.

  Blueprint Object Attributes

  ID (string, required) – Unique identifier of the Blueprint.
  Name (string, required) – The name of the Blueprint.
  Status (enum, required) – Current state of the Blueprint build (e.g., provisioning, building, build_complete, failed).
  Create time (integer, required) – Timestamp (ms) when the Blueprint was created.
  Parameters (object, required) – Configuration used to create the Blueprint.
  Failure reason (enum, optional) – Reason for failure if the build failed (e.g., out_of_memory, out_of_disk, build_failed).

  BLUEPRINT OPERATIONS

  List all Blueprints:
      page = client.blueprints.list()
  Create a new Blueprint:
      blueprint_view = client.blueprints.create(name="custom_blueprint")
  Retrieve a Blueprint by ID:
      blueprint_view = client.blueprints.retrieve(id="blueprint_id")
  Retrieve build logs for a Blueprint:
      blueprint_logs = client.blueprints.logs(id="blueprint_id")
  Preview a Blueprint before creation:
      blueprint_preview = client.blueprints.preview(name="custom_blueprint")

  Blueprints accelerate Devbox setup by caching pre-configured environments, making them ideal for reproducible and scalable development workflows.


  EXECUTION GUIDELINES:

  Always shutdown Devboxes after use to free up resources.
  Use execute_async for non-blocking commands.
  Handle API errors using try/except blocks.
  Use tunnels for exposing services running inside Devboxes.
  Use snapshots to persist Devbox states.