Devbox¶

The AsyncDevbox class provides asynchronous methods for managing and interacting with a devbox instance.

Asynchronous devbox resource class.

class runloop_api_client.sdk.async_devbox.AsyncDevbox(client, devbox_id)[source]¶

High-level async interface for managing a Runloop devbox.

This class provides a Pythonic, awaitable API for interacting with devboxes, including command execution, file operations, networking, and lifecycle management.

Example

>>> devbox = await sdk.devbox.create(name="my-devbox")
>>> async with devbox:
...     result = await devbox.cmd.exec(command="echo 'hello'")
...     print(await result.stdout())
# Devbox is automatically shut down on exit

property id: str¶

Return the devbox identifier.

Returns:: Unique devbox ID
Return type:: str

async get_info(**options)[source]¶

Retrieve current devbox status and metadata.

Parameters:: options (Unpack[BaseRequestOptions]) – Optional request configuration
Returns:: Current devbox state info
Return type:: DevboxView

async await_running(*, polling_config=None)[source]¶

Wait for the devbox to reach running state.

Parameters:: polling_config (PollingConfig | None, optional) – Optional polling behavior overrides, defaults to None
Returns:: Devbox state info after it reaches running status
Return type:: DevboxView

async await_suspended(*, polling_config=None)[source]¶

Wait for the devbox to reach suspended state.

Parameters:: polling_config (PollingConfig | None, optional) – Optional polling behavior overrides, defaults to None
Returns:: Devbox state info after it reaches suspended status
Return type:: DevboxView

async shutdown(**options)[source]¶

Shutdown the devbox, terminating all processes and releasing resources.

Parameters:: options (Unpack[LongRequestOptions]) – Optional long-running request configuration
Returns:: Final devbox state info
Return type:: DevboxView

async suspend(**options)[source]¶

Suspend the devbox without destroying state.

Returns immediately after issuing the suspend request. Call await_suspended() if you need to wait for the devbox to reach the suspended state (contrast with the synchronous SDK, which blocks).

Parameters:: options (Unpack[LongRequestOptions]) – Optional long-running request configuration
Returns:: Suspended devbox state info
Return type:: DevboxView

async resume(**options)[source]¶

Resume a suspended devbox.

Returns immediately after issuing the resume request. Call await_running() if you need to wait for the devbox to reach the running state (contrast with the synchronous SDK, which blocks).

Parameters:: options (Unpack[LongRequestOptions]) – Optional long-running request configuration
Returns:: Resumed devbox state info
Return type:: DevboxView

async keep_alive(**options)[source]¶

Extend the devbox timeout, preventing automatic shutdown.

Call this periodically for long-running workflows to prevent the devbox from being automatically shut down due to inactivity.

Parameters:: options (Unpack[LongRequestOptions]) – Optional long-running request configuration
Returns:: Response confirming the keep-alive request
Return type:: object

async snapshot_disk(**params)[source]¶

Create a disk snapshot of the devbox and wait for completion.

Captures the current state of the devbox disk, which can be used to create new devboxes with the same state.

Parameters:: params (Unpack[SDKDevboxSnapshotDiskParams]) – See SDKDevboxSnapshotDiskParams for available parameters
Returns:: Wrapper representing the completed snapshot
Return type:: AsyncSnapshot

async snapshot_disk_async(**params)[source]¶

Create a disk snapshot of the devbox asynchronously.

Starts the snapshot creation process and returns immediately without waiting for completion. Use snapshot.await_completed() to wait for completion.

Parameters:: params (Unpack[SDKDevboxSnapshotDiskAsyncParams]) – See SDKDevboxSnapshotDiskAsyncParams for available parameters
Returns:: Wrapper representing the snapshot request
Return type:: AsyncSnapshot

async close()[source]¶

Alias for shutdown() to support common resource patterns.

Return type:: None

property cmd: AsyncCommandInterface¶

Return the command execution interface.

Returns:: Helper for running shell commands
Return type:: AsyncCommandInterface

property file: AsyncFileInterface¶

Return the file operations interface.

Returns:: Helper for reading/writing files
Return type:: AsyncFileInterface

property net: AsyncNetworkInterface¶

Return the networking interface.

Returns:: Helper for SSH keys and tunnels
Return type:: AsyncNetworkInterface

class runloop_api_client.sdk.async_devbox.AsyncCommandInterface(devbox)[source]¶

Interface for executing commands on a devbox.

Accessed via devbox.cmd property. Provides exec() for synchronous execution and exec_async() for asynchronous execution with process management.

async exec(**params)[source]¶

Execute a command synchronously and wait for completion.

Parameters:: params (Unpack[SDKDevboxExecuteParams]) – See SDKDevboxExecuteParams for available parameters
Returns:: Wrapper with exit status and output helpers
Return type:: AsyncExecutionResult

Example

>>> result = await devbox.cmd.exec(command="echo 'hello'")
>>> print(await result.stdout())
>>> print(f"Exit code: {result.exit_code}")

async exec_async(**params)[source]¶

Execute a command asynchronously without waiting for completion.

Starts command execution and returns immediately with an AsyncExecution object for process management. Use execution.result() to wait for completion or execution.kill() to terminate the process.

Parameters:: params (Unpack[SDKDevboxExecuteAsyncParams]) – See SDKDevboxExecuteAsyncParams for available parameters
Returns:: Handle for managing the running process
Return type:: AsyncExecution

Example

>>> execution = await devbox.cmd.exec_async(command="sleep 10")
>>> state = await execution.get_state()
>>> print(f"Status: {state.status}")
>>> await execution.kill()  # Terminate early if needed

class runloop_api_client.sdk.async_devbox.AsyncFileInterface(devbox)[source]¶

Interface for file operations on a devbox.

Accessed via devbox.file property. Provides coroutines for reading, writing, uploading, and downloading files.

async read(**params)[source]¶

Read a file from the devbox.

Parameters:: params (Unpack[SDKDevboxReadFileContentsParams]) – See SDKDevboxReadFileContentsParams for available parameters
Returns:: File contents
Return type:: str

Example

>>> content = await devbox.file.read(path="/home/user/data.txt")
>>> print(content)

async write(**params)[source]¶

Write contents to a file in the devbox.

Creates or overwrites the file at the specified path.

Parameters:: params (Unpack[SDKDevboxWriteFileContentsParams]) – See SDKDevboxWriteFileContentsParams for available parameters
Returns:: Execution metadata for the write command
Return type:: DevboxExecutionDetailView

Example

>>> await devbox.file.write(file_path="/home/user/config.json", contents='{"key": "value"}')

async download(**params)[source]¶

Download a file from the devbox.

Parameters:: params (Unpack[SDKDevboxDownloadFileParams]) – See SDKDevboxDownloadFileParams for available parameters
Returns:: Raw file contents
Return type:: bytes

Example

>>> data = await devbox.file.download(path="/home/user/output.bin")
>>> with open("local_output.bin", "wb") as f:
...     f.write(data)

async upload(**params)[source]¶

Upload a file to the devbox.

Parameters:: params (Unpack[SDKDevboxUploadFileParams]) – See SDKDevboxUploadFileParams for available parameters
Returns:: API response confirming the upload
Return type:: object

Example

>>> from pathlib import Path
>>> await devbox.file.upload(path="/home/user/data.csv", file=Path("local_data.csv"))

class runloop_api_client.sdk.async_devbox.AsyncNetworkInterface(devbox)[source]¶

Interface for networking operations on a devbox.

Accessed via devbox.net property. Provides coroutines for SSH access and tunneling.

async create_ssh_key(**options)[source]¶

Create an SSH key for remote access to the devbox.

Parameters:: options (Unpack[LongRequestOptions]) – Optional long-running request configuration
Returns:: Response containing SSH connection info
Return type:: DevboxCreateSSHKeyResponse

Example

>>> ssh_key = await devbox.net.create_ssh_key()
>>> print(f"SSH URL: {ssh_key.url}")

async create_tunnel(**params)[source]¶

Create a network tunnel to expose a devbox port publicly.

Parameters:: params (Unpack[SDKDevboxCreateTunnelParams]) – See SDKDevboxCreateTunnelParams for available parameters
Returns:: Details about the public endpoint
Return type:: DevboxTunnelView

Example

>>> tunnel = await devbox.net.create_tunnel(port=8080)
>>> print(f"Public URL: {tunnel.url}")

async remove_tunnel(**params)[source]¶

Remove a network tunnel, disabling public access to the port.

Parameters:: params (Unpack[SDKDevboxRemoveTunnelParams]) – See SDKDevboxRemoveTunnelParams for available parameters
Returns:: Response confirming the tunnel removal
Return type:: object

Example

>>> await devbox.net.remove_tunnel(port=8080)