Asynchronous SDK¶

The asynchronous SDK provides a non-blocking interface for managing devboxes, blueprints, snapshots, and storage objects. Use this variant when working with async/await Python code.

Core Module¶

The core asynchronous SDK module provides async operation classes.

class runloop_api_client.sdk.async_.AsyncRunloopSDK(*, bearer_token=None, base_url=None, timeout=NOT_GIVEN, max_retries=5, default_headers=None, default_query=None, http_client=None)¶

High-level asynchronous entry point for the Runloop SDK.

Provides a Pythonic, object-oriented interface for managing devboxes, blueprints, snapshots, and storage objects. Exposes the generated async REST client via the api attribute for advanced use cases.

Variables:

api (AsyncRunloop) – Direct access to the generated async REST API client
devbox (AsyncDevboxOps) – High-level async interface for devbox management
blueprint (AsyncBlueprintOps) – High-level async interface for blueprint management
snapshot (AsyncSnapshotOps) – High-level async interface for snapshot management
storage_object (AsyncStorageObjectOps) – High-level async interface for storage object management

Example

>>> runloop = AsyncRunloopSDK()  # Uses RUNLOOP_API_KEY env var
>>> devbox = await runloop.devbox.create(name="my-devbox")
>>> result = await devbox.cmd.exec(command="echo 'hello'")
>>> print(await result.stdout())
>>> await devbox.shutdown()

async aclose()[source]¶

Close the underlying HTTP client and release resources.

Return type:: None

Asynchronous SDK entry points and management interfaces.

class runloop_api_client.sdk.async_.AsyncBlueprintOps(client)[source]¶

High-level async manager for creating and managing blueprints.

Accessed via runloop.blueprint from AsyncRunloopSDK, provides coroutines to create Dockerfile-based blueprints, inspect build logs, and list existing blueprints.

Example

>>> runloop = AsyncRunloopSDK()
>>> blueprint = await runloop.blueprint.create(
...     name="my-blueprint",
...     dockerfile="FROM ubuntu:22.04\nRUN apt-get update",
... )
>>> blueprints = await runloop.blueprint.list()

async create(**params)[source]¶

Create a blueprint and wait for the build to finish.

Parameters:: params (Unpack[SDKBlueprintCreateParams]) – See SDKBlueprintCreateParams for available parameters
Returns:: Wrapper bound to the finished blueprint
Return type:: AsyncBlueprint

from_id(blueprint_id)[source]¶

Return a blueprint wrapper for the given ID.

Parameters:: blueprint_id (str) – Blueprint ID to wrap
Returns:: Wrapper for the blueprint resource
Return type:: AsyncBlueprint

async list(**params)[source]¶

List available blueprints.

Parameters:: params (Unpack[SDKBlueprintListParams]) – See SDKBlueprintListParams for available parameters
Returns:: Blueprint wrappers for each record
Return type:: list[AsyncBlueprint]

class runloop_api_client.sdk.async_.AsyncDevboxOps(client)[source]¶

High-level async manager for creating and managing AsyncDevbox instances.

Accessed via runloop.devbox from AsyncRunloopSDK, provides coroutines to create devboxes from scratch, blueprints, or snapshots, and to list existing devboxes.

Example

>>> runloop = AsyncRunloopSDK()
>>> devbox = await runloop.devbox.create(name="my-devbox")
>>> devboxes = await runloop.devbox.list(limit=10)

async create(**params)[source]¶

Provision a new devbox and wait until it reaches running state.

Parameters:: params (Unpack[SDKDevboxCreateParams]) – See SDKDevboxCreateParams for available parameters
Returns:: Wrapper bound to the newly created devbox
Return type:: AsyncDevbox

async create_from_blueprint_id(blueprint_id, **params)[source]¶

Create a devbox from an existing blueprint by identifier.

Parameters:

blueprint_id (str) – Blueprint ID to create from
params (Unpack[SDKDevboxCreateFromImageParams]) – See SDKDevboxCreateFromImageParams for available parameters

Returns:

Wrapper bound to the newly created devbox

Return type:

AsyncDevbox

async create_from_blueprint_name(blueprint_name, **params)[source]¶

Create a devbox from the latest blueprint with the given name.

Parameters:

blueprint_name (str) – Blueprint name to create from
params (Unpack[SDKDevboxCreateFromImageParams]) – See SDKDevboxCreateFromImageParams for available parameters

Returns:

Wrapper bound to the newly created devbox

Return type:

AsyncDevbox

async create_from_snapshot(snapshot_id, **params)[source]¶

Create a devbox initialized from a snapshot.

Parameters:

snapshot_id (str) – Snapshot ID to create from
params (Unpack[SDKDevboxCreateFromImageParams]) – See SDKDevboxCreateFromImageParams for available parameters

Returns:

Wrapper bound to the newly created devbox

Return type:

AsyncDevbox

from_id(devbox_id)[source]¶

Attach to an existing devbox by ID.

Returns immediately without waiting for the devbox to reach running state. Call await_running() on the returned AsyncDevbox if you need to wait for readiness (contrast with the synchronous SDK, which blocks).

Parameters:: devbox_id (str) – Existing devbox ID
Returns:: Wrapper bound to the requested devbox
Return type:: AsyncDevbox

async list(**params)[source]¶

List devboxes accessible to the caller.

Parameters:: params (Unpack[SDKDevboxListParams]) – See SDKDevboxListParams for available parameters
Returns:: Collection of devbox wrappers
Return type:: list[AsyncDevbox]

class runloop_api_client.sdk.async_.AsyncSnapshotOps(client)[source]¶

High-level async manager for working with disk snapshots.

Accessed via runloop.snapshot from AsyncRunloopSDK, provides coroutines to list snapshots and access snapshot details.

Example

>>> runloop = AsyncRunloopSDK()
>>> snapshots = await runloop.snapshot.list(devbox_id="dev-123")
>>> snapshot = await runloop.snapshot.from_id("snap-123")

from_id(snapshot_id)[source]¶

Return a snapshot wrapper for the given ID.

Parameters:: snapshot_id (str) – Snapshot ID to wrap
Returns:: Wrapper for the snapshot resource
Return type:: AsyncSnapshot

async list(**params)[source]¶

List snapshots created from devboxes.

Parameters:: params (Unpack[SDKDiskSnapshotListParams]) – See SDKDiskSnapshotListParams for available parameters
Returns:: Snapshot wrappers for each record
Return type:: list[AsyncSnapshot]

class runloop_api_client.sdk.async_.AsyncStorageObjectOps(client)[source]¶

High-level async manager for creating and managing storage objects.

Accessed via runloop.storage_object from AsyncRunloopSDK, provides coroutines to create, upload, download, and list storage objects with convenient helpers for file and text uploads.

Example

>>> runloop = AsyncRunloopSDK()
>>> obj = await runloop.storage_object.upload_from_text("Hello!", "greeting.txt")
>>> content = await obj.download_as_text()
>>> objects = await runloop.storage_object.list()

async create(**params)[source]¶

Create a storage object and obtain an upload URL.

Parameters:: params (Unpack[SDKObjectCreateParams]) – See SDKObjectCreateParams for available parameters
Returns:: Wrapper with upload URL set for immediate uploads
Return type:: AsyncStorageObject

from_id(object_id)[source]¶

Return a storage object wrapper by identifier.

Parameters:: object_id (str) – Storage object identifier to wrap
Returns:: Wrapper for the storage object resource
Return type:: AsyncStorageObject

async list(**params)[source]¶

List storage objects owned by the caller.

Parameters:: params (Unpack[SDKObjectListParams]) – See SDKObjectListParams for available parameters
Returns:: Storage object wrappers for each record
Return type:: list[AsyncStorageObject]

async upload_from_bytes(data, name, *, content_type, metadata=None, **options)[source]¶

Create and upload an object from a bytes payload.

Parameters:

data (bytes) – Binary payload to upload
name (str) – Object display name
content_type (ContentType) – MIME type describing the payload
metadata (Optional[Dict[str, str]], optional) – Optional key-value metadata, defaults to None
options (Unpack[LongRequestOptions]) – See LongRequestOptions for available options

Returns:

Wrapper for the uploaded object

Return type:

AsyncStorageObject

async upload_from_file(file_path, name=None, *, content_type=None, metadata=None, **options)[source]¶

Create and upload an object from a local file path.

Parameters:

file_path (str | Path) – Local filesystem path to read
name (str | None, optional) – Optional object name; defaults to the file name, defaults to None
content_type (ContentType | None, optional) – Optional MIME type to apply to the object, defaults to None
metadata (Optional[Dict[str, str]], optional) – Optional key-value metadata, defaults to None
options (Unpack[LongRequestOptions]) – See LongRequestOptions for available options

Returns:

Wrapper for the uploaded object

Return type:

AsyncStorageObject

Raises:

OSError – If the local file cannot be read

async upload_from_text(text, name, *, metadata=None, **options)[source]¶

Create and upload an object from a text payload.

Parameters:

text (str) – Text content to upload
name (str) – Object display name
metadata (Optional[Dict[str, str]], optional) – Optional key-value metadata, defaults to None
options (Unpack[LongRequestOptions]) – See LongRequestOptions for available options

Returns:

Wrapper for the uploaded object

Return type:

AsyncStorageObject

Resource Modules¶

Asynchronous resource classes for working with devboxes, blueprints, snapshots, and more.