Core Module

AsyncSync

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, api_pool_shards=8, background_pool_shards=16, transfer_pool_shards=2)

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

• agent (AsyncAgentOps) – High-level async interface for agent management.

• axon (AsyncAxonOps) – [Beta] High-level async interface for axon management

• 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

• network_policy (AsyncNetworkPolicyOps) – High-level async interface for network policy management

• gateway_config (AsyncGatewayConfigOps) – High-level async interface for gateway config management

• mcp_config (AsyncMcpConfigOps) – High-level async interface for MCP config management

• secret (AsyncSecretOps) – High-level async interface for secret management

Example

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

async aclose()

Close the underlying HTTP client and release resources.

Return type:

None

Asynchronous SDK entry points and management interfaces.

class runloop_api_client.sdk.async_.AsyncDevboxOps(client)

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)

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)

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)

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)

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)

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)

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)

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")

async list(**params)

List snapshots created from devboxes.

Parameters:

params (Unpack[SDKDiskSnapshotListParams]) – See SDKDiskSnapshotListParams for available parameters

Returns:

Snapshot wrappers for each record

Return type:

list[AsyncSnapshot]

from_id(snapshot_id)

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

class runloop_api_client.sdk.async_.AsyncBlueprintOps(client)

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()

To use a local directory as a build context, use an object.

Example

>>> from datetime import timedelta
>>> from runloop_api_client.types.blueprint_build_parameters import BuildContext
>>> runloop = AsyncRunloopSDK()
>>> obj = await runloop.object_storage.upload_from_dir(
...     "./",
...     ttl=timedelta(hours=1),
... )
>>> blueprint = await runloop.blueprint.create(
...     name="my-blueprint",
...     dockerfile="FROM ubuntu:22.04\nCOPY . .\n",
...     build_context=BuildContext(type="object", object_id=obj.id),
... )

async create(**params)

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)

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)

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_.AsyncStorageObjectOps(client)

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)

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)

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)

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_file(file_path, *, name=None, content_type=None, metadata=None, ttl=None, **options)

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:

AsyncStorageObject

Raises:

OSError – If the local file cannot be read

async upload_from_dir(dir_path, *, name=None, metadata=None, ttl=None, ignore=None, **options)

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

• ignore (Optional[TarFilter]) – Optional tar filter function compatible with tarfile.TarFile.add(). If provided, it will be called for each member to allow modification or exclusion (by returning None).

• options (Unpack[LongRequestOptions]) – See LongRequestOptions for available options

Returns:

Wrapper for the uploaded object

Return type:

AsyncStorageObject

Raises:

• OSError – If the local directory cannot be read

• ValueError – If dir_path does not point to a directory

async upload_from_text(text, *, name, metadata=None, ttl=None, **options)

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:

AsyncStorageObject

async upload_from_bytes(data, *, name, content_type, metadata=None, ttl=None, **options)

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:

AsyncStorageObject

class runloop_api_client.sdk.async_.AsyncAxonOps(client)

[Beta] Create and manage axons (async). Access via runloop.axon.

Example

>>> runloop = AsyncRunloopSDK()
>>> axon = await runloop.axon.create()
>>> await axon.publish(event_type="test", origin="USER_EVENT", payload="{}", source="sdk")

async create(**params)

[Beta] Create a new axon.

Return type:

AsyncAxon

from_id(axon_id)

Get an AsyncAxon instance for an existing axon ID.

Return type:

AsyncAxon

async list(**params)

[Beta] List all axons, including deleted axons.

Parameters:

params (Unpack[SDKAxonListParams]) – See SDKAxonListParams for available parameters

Returns:

Collection of axon wrappers

Return type:

list[AsyncAxon]

class runloop_api_client.sdk.async_.AsyncAgentOps(client)

High-level async manager for creating and managing agents.

Accessed via runloop.agent from AsyncRunloopSDK, provides coroutines to create, retrieve, and list agents from various sources (npm, pip, git, object storage).

Example

>>> runloop = AsyncRunloopSDK()
>>> # Create agent from NPM package
>>> agent = await runloop.agent.create_from_npm(name="my-agent", package_name="@runloop/example-agent")
>>> # Create agent from Git repository
>>> agent = await runloop.agent.create_from_git(
...     name="git-agent", repository="https://github.com/user/agent-repo", ref="main"
... )
>>> # List all agents
>>> agents = await runloop.agent.list(limit=10)

async create(**params)

Create a new agent.

Parameters:

params (Unpack[SDKAgentCreateParams]) – See SDKAgentCreateParams for available parameters

Returns:

Wrapper bound to the newly created agent

Return type:

AsyncAgent

async create_from_npm(*, package_name, registry_url=None, agent_setup=None, **params)

Create an agent from an NPM package.

Parameters:

• package_name (str) – NPM package name

• registry_url (Optional[str], optional) – NPM registry URL, defaults to None

• agent_setup (Optional[list[str]], optional) – Setup commands to run after installation, defaults to None

• params (Unpack[SDKAgentCreateParams]) – See SDKAgentCreateParams for additional parameters (excluding ‘source’)

Returns:

Wrapper bound to the newly created agent

Return type:

AsyncAgent

Raises:

ValueError – If ‘source’ is provided in params

async create_from_pip(*, package_name, registry_url=None, agent_setup=None, **params)

Create an agent from a Pip package.

Parameters:

• package_name (str) – Pip package name

• registry_url (Optional[str], optional) – Pip registry URL, defaults to None

• agent_setup (Optional[list[str]], optional) – Setup commands to run after installation, defaults to None

• params (Unpack[SDKAgentCreateParams]) – See SDKAgentCreateParams for additional parameters (excluding ‘source’)

Returns:

Wrapper bound to the newly created agent

Return type:

AsyncAgent

Raises:

ValueError – If ‘source’ is provided in params

async create_from_git(*, repository, ref=None, agent_setup=None, **params)

Create an agent from a Git repository.

Parameters:

• repository (str) – Git repository URL

• ref (Optional[str], optional) – Optional Git ref (branch/tag/commit), defaults to main/HEAD

• agent_setup (Optional[list[str]], optional) – Setup commands to run after cloning, defaults to None

• params (Unpack[SDKAgentCreateParams]) – See SDKAgentCreateParams for additional parameters (excluding ‘source’)

Returns:

Wrapper bound to the newly created agent

Return type:

AsyncAgent

Raises:

ValueError – If ‘source’ is provided in params

async create_from_object(*, object_id, agent_setup=None, **params)

Create an agent from a storage object.

Parameters:

• object_id (str) – Storage object ID

• agent_setup (Optional[list[str]], optional) – Setup commands to run after unpacking, defaults to None

• params (Unpack[SDKAgentCreateParams]) – See SDKAgentCreateParams for additional parameters (excluding ‘source’)

Returns:

Wrapper bound to the newly created agent

Return type:

AsyncAgent

Raises:

ValueError – If ‘source’ is provided in params

from_id(agent_id)

Attach to an existing agent by ID.

Parameters:

agent_id (str) – Existing agent ID

Returns:

Wrapper bound to the requested agent

Return type:

AsyncAgent

async list(**params)

List agents accessible to the caller.

Parameters:

params (Unpack[SDKAgentListParams]) – See SDKAgentListParams for available parameters

Returns:

Collection of agent wrappers

Return type:

list[AsyncAgent]

async list_public(**params)

List public agents.

Parameters:

params (Unpack[SDKAgentListPublicParams]) – See SDKAgentListPublicParams for available parameters

Returns:

Collection of public agent wrappers

Return type:

list[AsyncAgent]

async devbox_counts(**options)

Get devbox counts grouped by agent name.

Parameters:

options (Unpack[BaseRequestOptions]) – Optional request configuration

Returns:

Devbox counts per agent name and total

Return type:

AgentDevboxCountsView

class runloop_api_client.sdk.async_.AsyncNetworkPolicyOps(client)

High-level async manager for creating and managing network policies.

Accessed via runloop.network_policy from AsyncRunloopSDK, provides coroutines to create, retrieve, update, delete, and list network policies.

Example

>>> runloop = AsyncRunloopSDK()
>>> policy = await runloop.network_policy.create(
...     name="my-policy",
...     allowed_hostnames=["github.com", "*.npmjs.org"],
... )
>>> policies = await runloop.network_policy.list()

async create(**params)

Create a new network policy.

Parameters:

params (Unpack[SDKNetworkPolicyCreateParams]) – See SDKNetworkPolicyCreateParams for available parameters

Returns:

The newly created network policy

Return type:

AsyncNetworkPolicy

from_id(network_policy_id)

Get an AsyncNetworkPolicy instance for an existing network policy ID.

Parameters:

network_policy_id (str) – ID of the network policy

Returns:

AsyncNetworkPolicy instance for the given ID

Return type:

AsyncNetworkPolicy

async list(**params)

List all network policies, optionally filtered by parameters.

Parameters:

params (Unpack[SDKNetworkPolicyListParams]) – See SDKNetworkPolicyListParams for available parameters

Returns:

List of network policies

Return type:

list[AsyncNetworkPolicy]

class runloop_api_client.sdk.async_.AsyncGatewayConfigOps(client)

High-level async manager for creating and managing gateway configurations.

Accessed via runloop.gateway_config from AsyncRunloopSDK, provides coroutines to create, retrieve, update, delete, and list gateway configs. Gateway configs define how to proxy API requests through the credential gateway, enabling secure API proxying without exposing API keys.

Example

>>> runloop = AsyncRunloopSDK()
>>> gateway_config = await runloop.gateway_config.create(
...     name="my-api-gateway",
...     endpoint="https://api.example.com",
...     auth_mechanism={"type": "bearer"},
... )
>>> # Use with a devbox
>>> devbox = await runloop.devbox.create(
...     name="my-devbox",
...     gateways={
...         "MY_API": {
...             "gateway": gateway_config.id,
...             "secret": "my-api-key-secret",
...         },
...     },
... )

async create(**params)

Create a new gateway config.

Example

>>> gateway_config = await runloop.gateway_config.create(
...     name="my-gateway",
...     endpoint="https://api.example.com",
...     auth_mechanism={"type": "header", "key": "x-api-key"},
...     description="Gateway for My API",
... )

Parameters:

params (Unpack[SDKGatewayConfigCreateParams]) – See SDKGatewayConfigCreateParams for available parameters

Returns:

The newly created gateway config

Return type:

AsyncGatewayConfig

from_id(gateway_config_id)

Get an AsyncGatewayConfig instance for an existing gateway config ID.

Example

>>> gateway_config = runloop.gateway_config.from_id("gwc_1234567890")
>>> info = await gateway_config.get_info()
>>> print(f"Gateway Config name: {info.name}")

Parameters:

gateway_config_id (str) – ID of the gateway config

Returns:

AsyncGatewayConfig instance for the given ID

Return type:

AsyncGatewayConfig

async list(**params)

List all gateway configs, optionally filtered by parameters.

Example

>>> configs = await runloop.gateway_config.list(limit=10)
>>> for config in configs:
...     print(config.id)

Parameters:

params (Unpack[SDKGatewayConfigListParams]) – See SDKGatewayConfigListParams for available parameters

Returns:

List of gateway configs

Return type:

list[AsyncGatewayConfig]

class runloop_api_client.sdk.async_.AsyncMcpConfigOps(client)

High-level async manager for creating and managing MCP configurations.

Accessed via runloop.mcp_config from AsyncRunloopSDK, provides methods to create, retrieve, update, delete, and list MCP configs. MCP configs define how to connect to upstream MCP (Model Context Protocol) servers, specifying the target endpoint and which tools are allowed.

Example

>>> runloop = AsyncRunloopSDK()
>>> mcp_config = await runloop.mcp_config.create(
...     name="my-mcp-server",
...     endpoint="https://mcp.example.com",
...     allowed_tools=["*"],
... )

async create(**params)

Create a new MCP config.

Parameters:

params (Unpack[SDKMcpConfigCreateParams]) – See SDKMcpConfigCreateParams for available parameters

Returns:

The newly created MCP config

Return type:

AsyncMcpConfig

from_id(mcp_config_id)

Get an AsyncMcpConfig instance for an existing MCP config ID.

Parameters:

mcp_config_id (str) – ID of the MCP config

Returns:

AsyncMcpConfig instance for the given ID

Return type:

AsyncMcpConfig

async list(**params)

List all MCP configs, optionally filtered by parameters.

Parameters:

params (Unpack[SDKMcpConfigListParams]) – See SDKMcpConfigListParams for available parameters

Returns:

List of MCP configs

Return type:

list[AsyncMcpConfig]

class runloop_api_client.sdk.async_.AsyncSecretOps(client)

High-level async manager for creating and managing Secrets.

Accessed via runloop.secret from AsyncRunloopSDK, provides methods to create, retrieve, update, list, and delete secrets. Secrets are encrypted key-value pairs that can be injected into Devboxes as environment variables.

Example

>>> runloop = AsyncRunloopSDK()
>>> secret = await runloop.secret.create(name="MY_API_KEY", value="secret-value")
>>> secrets = await runloop.secret.list()

async create(name, value, **options)

Create a new secret.

Example

>>> secret = await runloop.secret.create(
...     name="DATABASE_PASSWORD",
...     value="my-secure-password",
... )
>>> print(f"Created secret: {secret.name}")

Parameters:

• name (str) – Account-scoped secret name (must be a valid env var name)

• value (str) – Secret value to store (encrypted at rest)

• options (Unpack[LongRequestOptions]) – Optional request configuration

Returns:

The created AsyncSecret instance

Return type:

AsyncSecret

from_name(name)

Get an AsyncSecret instance by name without making an API call.

Use get_info() on the returned AsyncSecret to fetch the actual data.

Example

>>> secret = runloop.secret.from_name("MY_API_KEY")
>>> info = await secret.get_info()
>>> print(f"Secret ID: {info.id}")

Parameters:

name (str) – The literal account-scoped name of the secret

Returns:

An AsyncSecret instance (no API call made)

Return type:

AsyncSecret

from_id(id)

Get a lazy exact-ID handle; its operations never fall back to a name.

Return type:

AsyncSecretById

async update(secret, value, **options)

Update an existing secret’s value.

Example

>>> updated = await runloop.secret.update("DATABASE_PASSWORD", "new-password")
>>> # Or using an AsyncSecret object
>>> updated = await runloop.secret.update(secret, "new-password")

Parameters:

• secret (AsyncSecret | str) – The secret to update (AsyncSecret object or name string)

• value (str) – The new secret value

• options (Unpack[LongRequestOptions]) – Optional request configuration

Returns:

The updated AsyncSecret instance

Return type:

AsyncSecret

async list(**options)

List all secrets.

Example

>>> secrets = await runloop.secret.list()
>>> for s in secrets:
...     print(s.name)

Parameters:

options (Unpack[BaseRequestOptions]) – Optional request configuration

Returns:

List of AsyncSecret instances

Return type:

list[AsyncSecret]

async delete(secret, **options)

Delete a secret. This action is irreversible.

Example

>>> await runloop.secret.delete("DATABASE_PASSWORD")
>>> # Or using an AsyncSecret object
>>> await runloop.secret.delete(secret)

Parameters:

• secret (AsyncSecret | str) – The secret to delete (AsyncSecret object or name string)

• options (Unpack[LongRequestOptions]) – Optional request configuration

Returns:

The deleted secret metadata

Return type:

SecretView

Base REST Client

The SDK wraps the generated REST client. The api attribute on AsyncRunloopSDK / RunloopSDK provides direct access.

class runloop_api_client.AsyncRunloop(*, bearer_token=None, base_url=None, timeout=NOT_GIVEN, max_retries=5, default_headers=None, default_query=None, http_client=None, shared_http_pool=True, api_pool_shards=8, background_pool_shards=16, transfer_pool_shards=2, _strict_response_validation=False)

class runloop_api_client.Runloop(*, bearer_token=None, base_url=None, timeout=NOT_GIVEN, max_retries=5, default_headers=None, default_query=None, http_client=None, shared_http_pool=True, api_pool_shards=8, background_pool_shards=16, transfer_pool_shards=2, _strict_response_validation=False)