Devbox

AsyncSync

Asynchronous devbox resource class.

class runloop_api_client.sdk.async_devbox.AsyncDevbox(client, devbox_id)

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 runloop.devbox.create(name="my-devbox")
>>> async with devbox:
...     result = await devbox.cmd.exec("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)

Retrieve current devbox status and metadata.

Parameters:

options (Unpack[BaseRequestOptions]) – Optional request configuration

Returns:

Current devbox state info

Return type:

DevboxView

async get_tunnel(**options)

Retrieve the V2 tunnel information for this devbox.

Parameters:

options (Unpack[BaseRequestOptions]) – Optional request configuration

Returns:

Tunnel details if a tunnel is enabled, None otherwise

Return type:

TunnelView | None

Example

>>> tunnel = await devbox.get_tunnel()
>>> if tunnel:
...     print(f"Tunnel key: {tunnel.tunnel_key}")

async get_tunnel_url(port, **options)

Get the public tunnel URL for a specific port.

Constructs the tunnel URL using the format: https://{port}-{tunnel_key}.tunnel.runloop.ai

Parameters:

• port (int) – The port number to construct the URL for

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

Returns:

The public tunnel URL if a tunnel is enabled, None otherwise

Return type:

str | None

Example

>>> url = await devbox.get_tunnel_url(8080)
>>> if url:
...     print(f"Access your service at: {url}")

async logs(*, execution_id=None, shell_name=None, **options)

Retrieve logs for the devbox.

Returns all logs from a running or completed devbox. Optionally filter by execution ID or shell name.

Parameters:

• execution_id (str | None, optional) – Filter logs by execution ID, defaults to None

• shell_name (str | None, optional) – Filter logs by shell name, defaults to None

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

Returns:

Log entries for the devbox

Return type:

DevboxLogsListView

Example

>>> logs = await devbox.logs()
>>> for log in logs.logs:
...     print(f"[{log.level}] {log.message}")

async await_running(*, polling_config=None)

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)

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)

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)

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(*, polling_config=None, **options)

Resume a suspended devbox, restoring it to running state.

Waits for the devbox to reach running state before returning.

Parameters:

• polling_config (PollingConfig | None, optional) – Optional polling behavior overrides, defaults to None

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

Returns:

Resumed devbox state info

Return type:

DevboxView

async resume_async(**options)

Resume a suspended devbox without waiting for it to reach running state.

Initiates the resume operation and returns immediately. Use await_running() to wait for the devbox to reach running state if needed.

Parameters:

options (Unpack[LongRequestOptions]) – Optional long-running request configuration

Returns:

Devbox state info immediately after resume request

Return type:

DevboxView

async keep_alive(**options)

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)

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)

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

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

shell(shell_name=None)

Create a named shell instance for stateful command execution.

Named shells are stateful and maintain environment variables and the current working directory (CWD) across commands, just like a real shell on your local computer. Commands executed through the same named shell instance will execute sequentially - the shell can only run one command at a time with automatic queuing. This ensures that environment changes and directory changes from one command are preserved for the next command.

Parameters:

shell_name (str | None, optional) – The name of the persistent shell session. If not provided, a UUID will be generated automatically.

Returns:

An AsyncNamedShell instance for executing commands in the named shell

Return type:

AsyncNamedShell

Example

>>> # Create a named shell with a custom name
>>> shell = await devbox.shell("my-session")
>>> # Create a named shell with an auto-generated UUID name
>>> shell2 = await devbox.shell()
>>> # Commands execute sequentially and share state
>>> await shell.exec("cd /app")
>>> await shell.exec("export MY_VAR=value")
>>> result = await shell.exec("echo $MY_VAR")  # Will output 'value'
>>> result = await shell.exec("pwd")  # Will output '/app'

class runloop_api_client.sdk.async_devbox.AsyncCommandInterface(devbox)

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(command, **params)

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("echo 'hello'")
>>> print(await result.stdout())
>>> print(f"Exit code: {result.exit_code}")

async exec_async(command, **params)

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

Interface for file operations on a devbox.

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

async read(**params)

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)

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)

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)

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.AsyncNamedShell(devbox, shell_name)

Interface for executing commands in a persistent, stateful shell session.

Named shells are stateful and maintain environment variables and the current working directory (CWD) across commands. Commands executed through the same named shell instance will execute sequentially - the shell can only run one command at a time with automatic queuing. This ensures that environment changes and directory changes from one command are preserved for the next command.

Use AsyncDevbox.shell() to create a named shell instance. If you use the same shell name, it will re-attach to the existing named shell, preserving its state.

Example

>>> shell = await devbox.shell("my-session")
>>> await shell.exec("cd /app")
>>> await shell.exec("export MY_VAR=value")
>>> result = await shell.exec("echo $MY_VAR")  # Will output 'value'
>>> result = await shell.exec("pwd")  # Will output '/app'

async exec(command, **params)

Execute a command in the named shell and wait for it to complete.

The command will execute in the persistent shell session, maintaining environment variables and the current working directory from previous commands. Commands are queued and execute sequentially - only one command runs at a time in the named shell.

Optionally provide callbacks to stream logs in real-time. When callbacks are provided, this method waits for both the command to complete AND all streaming data to be processed before returning.

Parameters:

• command (str) – The command to execute

• params (Unpack[SDKDevboxExecuteParams]) – See SDKDevboxExecuteParams for available parameters

Returns:

Wrapper with exit status and output helpers

Return type:

AsyncExecutionResult

Example

>>> shell = await devbox.shell("my-session")
>>> result = await shell.exec("ls -la")
>>> print(await result.stdout())
>>> # With streaming callbacks
>>> result = await shell.exec("npm install", stdout=lambda line: print(f"[LOG] {line}"))

async exec_async(command, **params)

Execute a command in the named shell asynchronously without waiting for completion.

The command will execute in the persistent shell session, maintaining environment variables and the current working directory from previous commands. Commands are queued and execute sequentially - only one command runs at a time in the named shell.

Optionally provide callbacks to stream logs in real-time as they are produced. Callbacks fire in real-time as logs arrive. When you call execution.result(), it will wait for both the command to complete and all streaming to finish.

Parameters:

• command (str) – The command to execute

• params (Unpack[SDKDevboxExecuteAsyncParams]) – See SDKDevboxExecuteAsyncParams for available parameters

Returns:

Handle for managing the running process

Return type:

AsyncExecution

Example

>>> shell = await devbox.shell("my-session")
>>> execution = await shell.exec_async("long-running-task.sh", stdout=lambda line: print(f"[LOG] {line}"))
>>> # Do other work while command runs...
>>> result = await execution.result()
>>> if result.success:
...     print("Task completed successfully!")

class runloop_api_client.sdk.async_devbox.AsyncNetworkInterface(devbox)

Interface for networking operations on a devbox.

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

async create_ssh_key(**options)

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 enable_tunnel(**params)

Enable a V2 tunnel for secure HTTP access to the devbox.

V2 tunnels provide encrypted URL-based access without exposing internal IDs. Each devbox can have one tunnel. The tunnel URL format is: https://{port}-{tunnel_key}.tunnel.runloop.ai

Parameters:

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

Returns:

Tunnel details including the tunnel key for constructing URLs

Return type:

TunnelView

Example

>>> tunnel = await devbox.net.enable_tunnel(auth_mode="open")
>>> print(f"Tunnel key: {tunnel.tunnel_key}")
>>> # Access via: https://8080-{tunnel.tunnel_key}.tunnel.runloop.ai

async remove_tunnel(**params)

Remove a tunnel from the devbox.

Parameters:

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

Returns:

Response confirming the tunnel removal

Return type:

object

Example

>>> await devbox.net.remove_tunnel()