Synchronous SDK¶

The synchronous SDK provides a blocking interface for managing devboxes, blueprints, snapshots, and storage objects. Use this variant when working in synchronous Python code.

Core Module¶

The core synchronous SDK module provides the main entry point and operation classes.

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

High-level synchronous entry point for the Runloop SDK.

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

Variables:

api (Runloop) – Direct access to the generated REST API client
devbox (DevboxOps) – High-level interface for devbox management
blueprint (BlueprintOps) – High-level interface for blueprint management
snapshot (SnapshotOps) – High-level interface for snapshot management
storage_object (StorageObjectOps) – High-level interface for storage object management

Example

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

close()[source]¶

Close the underlying HTTP client and release resources.

Return type:: None

Synchronous SDK entry points and management interfaces.

class runloop_api_client.sdk.sync.DevboxOps(client)[source]¶

High-level manager for creating and managing Devbox instances.

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

Example

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

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:: Devbox

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:

Devbox

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:

Devbox

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:

Devbox

from_id(devbox_id)[source]¶

Attach to an existing devbox by ID.

Blocks until the devbox reaches running state so callers can begin issuing commands immediately.

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

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[Devbox]

class runloop_api_client.sdk.sync.SnapshotOps(client)[source]¶

High-level manager for working with disk snapshots.

Accessed via runloop.snapshot from RunloopSDK, provides methods to list snapshots and access snapshot details.

Example

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

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[Snapshot]

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:: Snapshot

class runloop_api_client.sdk.sync.BlueprintOps(client)[source]¶

High-level manager for creating and managing blueprints.

Accessed via runloop.blueprint from RunloopSDK, provides methods to create blueprints with Dockerfiles and system setup commands, and to list existing blueprints.

Example

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

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:: Blueprint

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:: Blueprint

list(**params)[source]¶

List available blueprints.

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

class runloop_api_client.sdk.sync.StorageObjectOps(client)[source]¶

High-level manager for creating and managing storage objects.

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

Example

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

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:: StorageObject

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:: StorageObject

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[StorageObject]

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

Create and upload an object from a local file path.

Parameters:

file_path (str | Path) – Local filesystem path to read
name (Optional[str]) – Optional object name; defaults to the file name
content_type (Optional[ContentType]) – Optional MIME type to apply to the object
metadata (Optional[Dict[str, str]]) – Optional key-value metadata
ttl (Optional[timedelta]) – Optional Time-To-Live, after which the object is automatically deleted
options (Unpack[LongRequestOptions]) – See LongRequestOptions for available options

Returns:

Wrapper for the uploaded object

Return type:

StorageObject

Raises:

OSError – If the local file cannot be read

upload_from_dir(dir_path, *, name=None, metadata=None, ttl=None, **options)[source]¶

Create and upload an object from a local directory.

The resulting object will be uploaded as a compressed tarball.

Parameters:

dir_path (str | Path) – Local filesystem directory path to tar
name (Optional[str]) – Optional object name; defaults to the directory name + ‘.tar.gz’
metadata (Optional[Dict[str, str]]) – Optional key-value metadata
ttl (Optional[timedelta]) – Optional Time-To-Live, after which the object is automatically deleted
options (Unpack[LongRequestOptions]) – See LongRequestOptions for available options

Returns:

Wrapper for the uploaded object

Return type:

StorageObject

Raises:

OSError – If the local file cannot be read

upload_from_text(text, *, name, metadata=None, ttl=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 key-value metadata
ttl (Optional[timedelta]) – Optional Time-To-Live, after which the object is automatically deleted
options (Unpack[LongRequestOptions]) – See LongRequestOptions for available options

Returns:

Wrapper for the uploaded object

Return type:

StorageObject

upload_from_bytes(data, *, name, content_type, metadata=None, ttl=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 key-value metadata
ttl (Optional[timedelta]) – Optional Time-To-Live, after which the object is automatically deleted
options (Unpack[LongRequestOptions]) – See LongRequestOptions for available options

Returns:

Wrapper for the uploaded object

Return type:

StorageObject

Resource Modules¶

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