Devbox¶

The Devbox class provides synchronous methods for managing and interacting with a devbox instance.

Synchronous devbox resource class.

class runloop_api_client.sdk.devbox.Devbox(client, devbox_id)[source]¶

High-level interface for managing a Runloop devbox.

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

The Devbox class supports context manager protocol for automatic cleanup.

Example

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

property id: str¶

Return the devbox identifier.

Returns:: Unique devbox ID
Return type:: str

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

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

Wait for the devbox to reach running state.

Blocks until the devbox is running or the polling timeout is reached.

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

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

Wait for the devbox to reach suspended state.

Blocks until the devbox is suspended or the polling timeout is reached.

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

shutdown(**options)[source]¶

Shutdown the devbox, terminating all processes and releasing resources.

Parameters:: options (Unpack[LongRequestOptions]) – Long-running request configuration (timeouts, retries, etc.)
Returns:: Final devbox state info
Return type:: DevboxView

suspend(**options)[source]¶

Suspend the devbox, pausing execution while preserving state.

This saves resources while maintaining the devbox state for later resumption. Waits for the devbox to reach suspended state before returning.

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

resume(**options)[source]¶

Resume a suspended devbox, restoring it to running state.

Waits for the devbox to reach running state before returning.

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

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

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

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 (may still be processing)
Return type:: Snapshot

close()[source]¶

Alias for shutdown() to support common resource patterns.

Return type:: None

property cmd: CommandInterface¶

Return the command execution interface.

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

property file: FileInterface¶

Return the file operations interface.

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

property net: NetworkInterface¶

Return the networking interface.

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

class runloop_api_client.sdk.devbox.CommandInterface(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.

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

Example

>>> result = devbox.cmd.exec(command="ls -la")
>>> print(result.stdout())
>>> print(f"Exit code: {result.exit_code}")

exec_async(**params)[source]¶

Execute a command asynchronously without waiting for completion.

Starts command execution and returns immediately with an Execution 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:: Execution

Example

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

class runloop_api_client.sdk.devbox.FileInterface(devbox)[source]¶

Interface for file operations on a devbox.

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

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 = devbox.file.read("/home/user/data.txt")
>>> print(content)

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

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

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 = devbox.file.download("/home/user/output.bin")
>>> with open("local_output.bin", "wb") as f:
...     f.write(data)

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
>>> devbox.file.upload("/home/user/data.csv", Path("local_data.csv"))

class runloop_api_client.sdk.devbox.NetworkInterface(devbox)[source]¶

Interface for network operations on a devbox.

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

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 = devbox.net.create_ssh_key()
>>> print(f"SSH URL: {ssh_key.url}")

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 = devbox.net.create_tunnel(port=8080)
>>> print(f"Public URL: {tunnel.url}")

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

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