Sandbox

class Sandbox(SandboxDto)

Represents a Daytona Sandbox.

Attributes:

fs FileSystem - File system operations interface.
git Git - Git operations interface.
process Process - Process execution interface.
computer_use ComputerUse - Computer use operations interface for desktop automation.
code_interpreter CodeInterpreter - Stateful interpreter interface for executing code. Currently supports only Python. For other languages, use the process.code_run interface.
id str - Unique identifier for the Sandbox.
name str - Name of the Sandbox.
organization_id str - Organization ID of the Sandbox.
snapshot str | None - Daytona snapshot used to create the Sandbox.
user str - OS user running in the Sandbox.
env dict[str, str] | None - Environment variables set in the Sandbox (not returned by list results; call refresh_data() on each item to populate).
labels dict[str, str] - Custom labels attached to the Sandbox.
public bool - Whether the Sandbox is publicly accessible.
target str - Target location of the runner where the Sandbox runs.
cpu int - Number of CPUs allocated to the Sandbox.
gpu int - Number of GPUs allocated to the Sandbox.
memory int - Amount of memory allocated to the Sandbox in GiB.
disk int - Amount of disk space allocated to the Sandbox in GiB.
state SandboxState | None - Current state of the Sandbox (e.g., “started”, “stopped”).
error_reason str | None - Error message if Sandbox is in error state.
recoverable bool | None - Whether the Sandbox error is recoverable.
backup_state str | None - Current state of Sandbox backup.
backup_created_at str | None - When the backup was created (not returned by list results; call refresh_data() on each item to populate).
auto_stop_interval int | None - Auto-stop interval in minutes.
auto_pause_interval int | None - Auto-pause interval in minutes (0 means disabled). Only supported for sandbox classes that support pausing. At most one of auto_stop_interval and auto_pause_interval may be non-zero.
auto_archive_interval int | None - Auto-archive interval in minutes.
auto_delete_interval int | None - Auto-delete interval in minutes.
volumes list[SandboxVolume] | None - Volumes attached to the Sandbox (not returned by list results; call refresh_data() on each item to populate).
build_info BuildInfo | None - Build information for the Sandbox if it was created from dynamic build (not returned by list results; call refresh_data() on each item to populate).
created_at str | None - When the Sandbox was created.
updated_at str | None - When the Sandbox was last updated.
last_activity_at str | None - When the Sandbox last had activity.
network_block_all bool | None - Whether to block all network access for the Sandbox (not returned by list results; call refresh_data() on each item to populate).
network_allow_list str | None - Comma-separated list of allowed CIDR network addresses for the Sandbox (not returned by list results; call refresh_data() on each item to populate).
domain_allow_list str | None - Comma-separated list of allowed domains for the Sandbox (not returned by list results; call refresh_data() on each item to populate).
toolbox_proxy_url str - The toolbox proxy URL for the Sandbox.

env: `dict[str, str] | None`

env = None

pyright: ignore[reportRedeclaration]

network_block_all: `bool | None`

network_block_all = None

pyright: ignore[reportRedeclaration]

Sandbox.init

def __init__(sandbox_dto: SandboxDto | SandboxListItem,
             toolbox_api: ApiClient,
             sandbox_api: SandboxApi,
             language: str,
             http_client: httpx.Client,
             analytics_api_url_provider: Callable[[], str | None]
             | None = None)

Initialize a new Sandbox instance.

Arguments:

sandbox_dto SandboxDto | SandboxListItem - The sandbox data from the API.
toolbox_api ApiClient - API client for toolbox operations.
sandbox_api SandboxApi - API client for Sandbox operations.
http_client httpx.Client - Shared pooled client for file transfers.

Sandbox.refresh_data

@intercept_errors(message_prefix="Failed to refresh sandbox data: ")
@with_instrumentation()
def refresh_data(request_timeout: float | None = None) -> None

Refreshes the Sandbox data from the API.

Arguments:

request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Example:

sandbox.refresh_data()
print(f"Sandbox {sandbox.id}:")
print(f"State: {sandbox.state}")
print(f"Resources: {sandbox.cpu} CPU, {sandbox.memory} GiB RAM")

Sandbox.get_user_home_dir

@intercept_errors(message_prefix="Failed to get user home directory: ")
@with_instrumentation()
def get_user_home_dir() -> str

Gets the user’s home directory path inside the Sandbox.

Returns:

str - The absolute path to the user’s home directory inside the Sandbox.

Example:

user_home_dir = sandbox.get_user_home_dir()
print(f"Sandbox user home: {user_home_dir}")

Sandbox.get_work_dir

@intercept_errors(message_prefix="Failed to get working directory path: ")
@with_instrumentation()
def get_work_dir() -> str

Gets the working directory path inside the Sandbox.

Returns:

str - The absolute path to the Sandbox working directory. Uses the WORKDIR specified in the Dockerfile if present, or falling back to the user’s home directory if not.

Example:

work_dir = sandbox.get_work_dir()
print(f"Sandbox working directory: {work_dir}")

Sandbox.get_metrics_latest

@intercept_errors(message_prefix="Failed to get sandbox metrics: ")
@with_instrumentation()
def get_metrics_latest() -> SandboxMetrics

Gets the most recent resource usage sample directly from the Sandbox daemon.

Unlike :meth:get_metrics, which returns aggregated historical samples, this returns the single current reading without going through the telemetry backend.

Returns:

SandboxMetrics - The current CPU, memory, and disk usage sample for the Sandbox.

Sandbox.get_metrics

@intercept_errors(message_prefix="Failed to get sandbox metrics: ")
@with_instrumentation()
def get_metrics(start: datetime | None = None,
                end: datetime | None = None) -> list[SandboxMetrics]

Gets historical time-series resource usage metrics for the Sandbox.

When the deployment runs a dedicated Analytics API, metrics are fetched from it directly; otherwise they are fetched through the control-plane telemetry proxy.

Arguments:

start datetime | None - Start of the time range. Defaults to the Sandbox creation time.
end datetime | None - End of the time range. Defaults to the current time.

Returns:

list[SandboxMetrics] - Time-ordered usage samples over the requested range.

Sandbox.create_lsp_server

@with_instrumentation()
def create_lsp_server(language_id: LspLanguageId | LspLanguageIdLiteral,
                      path_to_project: str) -> LspServer

Creates a new Language Server Protocol (LSP) server instance.

The LSP server provides language-specific features like code completion, diagnostics, and more.

Arguments:

language_id LspLanguageId | LspLanguageIdLiteral - The language server type (e.g., LspLanguageId.PYTHON).
path_to_project str - Path to the project root directory. Relative paths are resolved based on the sandbox working directory.

Returns:

LspServer - A new LSP server instance configured for the specified language.

Example:

lsp = sandbox.create_lsp_server("python", "workspace/project")

Sandbox.set_labels

@intercept_errors(message_prefix="Failed to set labels: ")
@with_instrumentation()
def set_labels(labels: dict[str, str],
               request_timeout: float | None = None) -> dict[str, str]

Sets labels for the Sandbox.

Labels are key-value pairs that can be used to organize and identify Sandboxes.

Arguments:

labels dict[str, str] - Dictionary of key-value pairs representing Sandbox labels.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

dict[str, str]: Dictionary containing the updated Sandbox labels.

Example:

new_labels = sandbox.set_labels({
    "project": "my-project",
    "environment": "development",
    "team": "backend"
})
print(f"Updated labels: {new_labels}")

Sandbox.start

@intercept_errors(message_prefix="Failed to start sandbox: ")
@with_timeout()
@with_instrumentation()
def start(timeout: float | None = 60)

Starts the Sandbox and waits for it to be ready.

Arguments:

timeout float | None - Maximum time to wait in seconds. 0 means no timeout. Default is 60 seconds.

Raises:

DaytonaError - If timeout is negative. If sandbox fails to start or times out.

Example:

sandbox = daytona.get("my-sandbox-id")
sandbox.start(timeout=40)  # Wait up to 40 seconds
print("Sandbox started successfully")

Sandbox.recover

@intercept_errors(message_prefix="Failed to recover sandbox: ")
@with_timeout()
def recover(timeout: float | None = 60)

Recovers the Sandbox from a recoverable error and waits for it to be ready.

Arguments:

timeout float | None - Maximum time to wait in seconds. 0 means no timeout. Default is 60 seconds.

Raises:

DaytonaError - If timeout is negative. If sandbox fails to recover or times out.

Example:

sandbox = daytona.get("my-sandbox-id")
sandbox.recover(timeout=40)  # Wait up to 40 seconds
print("Sandbox recovered successfully")

Sandbox.stop

@intercept_errors(message_prefix="Failed to stop sandbox: ")
@with_timeout()
@with_instrumentation()
def stop(timeout: float | None = 60, force: bool = False)

Stops the Sandbox and waits for it to be fully stopped.

Arguments:

timeout float | None - Maximum time to wait in seconds. 0 means no timeout. Default is 60 seconds.
force bool - If True, uses SIGKILL instead of SIGTERM to stop the sandbox. Default is False.

Raises:

DaytonaError - If timeout is negative; If sandbox fails to stop or times out

Example:

sandbox = daytona.get("my-sandbox-id")
sandbox.stop()
print("Sandbox stopped successfully")

Sandbox.delete

@intercept_errors(message_prefix="Failed to remove sandbox: ")
@with_timeout()
@with_instrumentation()
def delete(timeout: float | None = 60) -> None

Deletes the Sandbox.

Arguments:

timeout float | None - Timeout (in seconds) for sandbox deletion. 0 means no timeout. Default is 60 seconds.

Sandbox.wait_for_sandbox_start

@intercept_errors(
    message_prefix="Failure during waiting for sandbox to start: ")
@with_timeout()
@with_instrumentation()
def wait_for_sandbox_start(timeout: float | None = 60) -> None

Waits for the Sandbox to reach the ‘started’ state. Polls the Sandbox status until it reaches the ‘started’ state, encounters an error or times out.

Arguments:

timeout float | None - Maximum time to wait in seconds. 0 means no timeout. Default is 60 seconds.

Raises:

DaytonaError - If timeout is negative; If Sandbox fails to start or times out

Sandbox.wait_for_sandbox_stop

@intercept_errors(
    message_prefix="Failure during waiting for sandbox to stop: ")
@with_timeout()
@with_instrumentation()
def wait_for_sandbox_stop(timeout: float | None = 60) -> None

Waits for the Sandbox to reach the ‘stopped’ state. Polls the Sandbox status until it reaches the ‘stopped’ state, encounters an error or times out. It will wait up to 60 seconds for the Sandbox to stop. Treats destroyed as stopped to cover ephemeral sandboxes that are automatically deleted after stopping.

Arguments:

timeout float | None - Maximum time to wait in seconds. 0 means no timeout. Default is 60 seconds.

Raises:

DaytonaError - If timeout is negative. If Sandbox fails to stop or times out.

Sandbox.set_autostop_interval

@intercept_errors(message_prefix="Failed to set auto-stop interval: ")
@with_instrumentation()
def set_autostop_interval(interval: int,
                          request_timeout: float | None = None) -> None

Sets the auto-stop interval for the Sandbox.

The Sandbox will automatically stop after being idle (no new events) for the specified interval. Events include any state changes or interactions with the Sandbox through the SDK. Interactions using Sandbox Previews are not included.

Arguments:

interval int - Number of minutes of inactivity before auto-stopping. Set to 0 to disable auto-stop. Defaults to 15.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Raises:

DaytonaValidationError - If interval is negative

Example:

# Auto-stop after 1 hour
sandbox.set_autostop_interval(60)
# Or disable auto-stop
sandbox.set_autostop_interval(0)

Sandbox.set_auto_pause_interval

@intercept_errors(message_prefix="Failed to set auto-pause interval: ")
@with_instrumentation()
def set_auto_pause_interval(interval: int) -> None

Sets the auto-pause interval for the Sandbox.

The Sandbox will automatically pause after being idle (no new events) for the specified interval. Only supported for sandbox classes that support pausing.

Arguments:

interval int - Number of minutes of inactivity before auto-pausing. Set to 0 to disable auto-pause.

Raises:

DaytonaValidationError - If interval is negative

Example:

# Auto-pause after 1 hour
sandbox.set_auto_pause_interval(60)
# Or disable auto-pause
sandbox.set_auto_pause_interval(0)

Sandbox.set_auto_archive_interval

@intercept_errors(message_prefix="Failed to set auto-archive interval: ")
@with_instrumentation()
def set_auto_archive_interval(interval: int,
                              request_timeout: float | None = None) -> None

Sets the auto-archive interval for the Sandbox.

The Sandbox will automatically archive after being continuously stopped for the specified interval.

Arguments:

interval int - Number of minutes after which a continuously stopped Sandbox will be auto-archived. Set to 0 for the maximum interval. Default is 7 days.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Raises:

DaytonaValidationError - If interval is negative

Example:

# Auto-archive after 1 hour
sandbox.set_auto_archive_interval(60)
# Or use the maximum interval
sandbox.set_auto_archive_interval(0)

Sandbox.set_auto_delete_interval

@intercept_errors(message_prefix="Failed to set auto-delete interval: ")
@with_instrumentation()
def set_auto_delete_interval(interval: int,
                             request_timeout: float | None = None) -> None

Sets the auto-delete interval for the Sandbox.

The Sandbox will automatically delete after being continuously stopped for the specified interval.

Arguments:

interval int - Number of minutes after which a continuously stopped Sandbox will be auto-deleted. Set to negative value to disable auto-delete. Set to 0 to delete immediately upon stopping. By default, auto-delete is disabled.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Example:

# Auto-delete after 1 hour
sandbox.set_auto_delete_interval(60)
# Or delete immediately upon stopping
sandbox.set_auto_delete_interval(0)
# Or disable auto-delete
sandbox.set_auto_delete_interval(-1)

Sandbox.update_network_settings

@intercept_errors(message_prefix="Failed to update network settings: ")
@with_instrumentation()
def update_network_settings(*,
                            network_block_all: bool | None = None,
                            network_allow_list: str | None = None,
                            domain_allow_list: str | None = None,
                            request_timeout: float | None = None) -> None

Updates outbound network policy on the runner (block all, restore access, or CIDR allow list).

Arguments:

network_block_all - When True, blocks all outbound traffic. When False, restores general outbound access (and clears a stored allow list).
network_allow_list - Comma-separated IPv4 CIDRs to allow; implies not blocking all.
domain_allow_list - Comma-separated domains to allow; implies not blocking all.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Raises:

DaytonaValidationError - If neither argument is set.

Example:

sandbox.update_network_settings(network_block_all=True)
sandbox.update_network_settings(network_block_all=False)

Sandbox.update_secrets

@intercept_errors(message_prefix="Failed to update secrets: ")
@with_instrumentation()
def update_secrets(secrets: dict[str, str]) -> None

Updates the set of vault secrets mounted in the Sandbox, replacing the previously mounted set.

Attached, detached and rotated secrets take effect for outbound requests within seconds. New environment variables only become visible to processes spawned after the update, and a Sandbox created without any secrets must be restarted for newly attached secrets to work.

Arguments:

secrets dict[str, str] - Map of environment variable name to the name of an existing organization Secret. Pass an empty dict to detach all secrets.

Example:

sandbox.update_secrets({"ANTHROPIC_API_KEY": "anthropic-prod"})
sandbox.update_secrets({})  # detach all

Sandbox.update_env

@intercept_errors(message_prefix="Failed to update environment: ")
@with_instrumentation()
def update_env(env: dict[str, str], *, unset: list[str] | None = None) -> None

Updates the Sandbox daemon’s process environment.

Newly spawned processes, sessions and PTYs inherit the change; already-running processes keep their environment.

Arguments:

env dict[str, str] - Environment variables to set.
unset list[str] | None - Environment variable names to remove before env is applied.

Example:

sandbox.update_env({"MY_VAR": "value"}, unset=["OLD_VAR"])

Sandbox.get_preview_link

@intercept_errors(message_prefix="Failed to get preview link: ")
@with_instrumentation()
def get_preview_link(port: int,
                     request_timeout: float | None = None) -> PortPreviewUrl

Retrieves the preview link for the sandbox at the specified port. If the port is closed, it will be opened automatically. For private sandboxes, a token is included to grant access to the URL.

Arguments:

port int - The port to open the preview link on.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

PortPreviewUrl - The response object for the preview link, which includes the url and the token (to access private sandboxes).

Example:

preview_link = sandbox.get_preview_link(3000)
print(f"Preview URL: {preview_link.url}")
print(f"Token: {preview_link.token}")

Sandbox.create_signed_preview_url

@intercept_errors(message_prefix="Failed to create signed preview url: ")
def create_signed_preview_url(
        port: int,
        expires_in_seconds: int | None = None,
        request_timeout: float | None = None) -> SignedPortPreviewUrl

Creates a signed preview URL for the sandbox at the specified port.

Arguments:

port int - The port to open the preview link on.
expires_in_seconds int | None - The number of seconds the signed preview url will be valid for. Defaults to 60 seconds.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Returns:

SignedPortPreviewUrl - The response object for the signed preview url.

Sandbox.expire_signed_preview_url

@intercept_errors(message_prefix="Failed to expire signed preview url: ")
def expire_signed_preview_url(port: int,
                              token: str,
                              request_timeout: float | None = None) -> None

Expires a signed preview URL for the sandbox at the specified port.

Arguments:

port int - The port to expire the signed preview url on.
token str - The token to expire the signed preview url on.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Sandbox.archive

@intercept_errors(message_prefix="Failed to archive sandbox: ")
@with_instrumentation()
def archive(request_timeout: float | None = None) -> None

Archives the sandbox, making it inactive and preserving its state. When sandboxes are archived, the entire filesystem state is moved to cost-effective object storage, making it possible to keep sandboxes available for an extended period. The tradeoff between archived and stopped states is that starting an archived sandbox takes more time, depending on its size. Sandbox must be stopped before archiving.

Arguments:

request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Sandbox.resize

@intercept_errors(message_prefix="Failed to resize sandbox: ")
@with_timeout()
@with_instrumentation()
def resize(resources: Resources, timeout: float | None = 60) -> None

Resizes the Sandbox resources.

Changes the CPU, memory, or disk allocation. Hot resize (on a running Sandbox) accepts only CPU and memory increases. Disk resize requires a stopped Sandbox; disk can only grow. GPU is not resizable — to change GPU, create a new Sandbox.

Arguments:

resources Resources - New resource configuration. Only cpu, memory, and disk are applied; setting gpu or gpu_type raises an error.
timeout Optional[float] - Timeout in seconds for the resize operation. 0 means no timeout. Default is 60 seconds.

Raises:

DaytonaError - If hot-resize constraints are violated, disk resize is attempted on a running Sandbox, disk decrease is attempted, no fields are provided, gpu or gpu_type is set, or the operation times out.

Example:

sandbox.resize(Resources(cpu=4, memory=8))

sandbox.stop()
sandbox.resize(Resources(cpu=2, memory=4, disk=30))

Sandbox.wait_for_resize_complete

@intercept_errors(
    message_prefix="Failure during waiting for resize to complete: ")
@with_timeout()
@with_instrumentation()
def wait_for_resize_complete(timeout: float | None = 60) -> None

Waits for the Sandbox resize operation to complete. Polls the Sandbox status until the state is no longer ‘resizing’.

Arguments:

timeout Optional[float] - Maximum time to wait in seconds. 0 means no timeout. Default is 60 seconds.

Raises:

DaytonaError - If timeout is negative. If resize operation times out.

Sandbox.create_ssh_access

@intercept_errors(message_prefix="Failed to create SSH access: ")
@with_instrumentation()
def create_ssh_access(expires_in_minutes: int | None = None,
                      request_timeout: float | None = None) -> SshAccessDto

Creates an SSH access token for the sandbox.

Arguments:

expires_in_minutes int | None - The number of minutes the SSH access token will be valid for.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Sandbox.revoke_ssh_access

@intercept_errors(message_prefix="Failed to revoke SSH access: ")
@with_instrumentation()
def revoke_ssh_access(token: str,
                      request_timeout: float | None = None) -> None

Revokes an SSH access token for the sandbox.

Arguments:

token str - The token to revoke.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Sandbox.validate_ssh_access

@intercept_errors(message_prefix="Failed to validate SSH access: ")
@with_instrumentation()
def validate_ssh_access(
        token: str,
        request_timeout: float | None = None) -> SshAccessValidationDto

Validates an SSH access token for the sandbox.

Arguments:

token str - The token to validate.
request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Sandbox.refresh_activity

@intercept_errors(message_prefix="Failed to refresh sandbox activity: ")
def refresh_activity(request_timeout: float | None = None) -> None

Refreshes the sandbox activity to reset the timer for automated lifecycle management actions.

This method updates the sandbox’s last activity timestamp without changing its state. It is useful for keeping long-running sessions alive while there is still user activity.

Arguments:

request_timeout float | None - Optional client-side request timeout in seconds. Client-side only. It bounds how long the SDK waits for the HTTP response and does not cancel the operation on the server. Positive values under 1 second are rounded up to 1 second; 0 disables the client-side timeout and negative values are rejected.

Example:

sandbox.refresh_activity()

Sandbox.pause

@intercept_errors(message_prefix="Failed to pause sandbox")
@with_instrumentation()
def pause(timeout: float = 60) -> None

Pauses the Sandbox, freezing all running processes.

The Sandbox will enter a ‘pausing’ state and transition to ‘paused’ when complete. While paused, the Sandbox retains its state in memory but does not consume CPU cycles.

Arguments:

timeout - Maximum time to wait in seconds. 0 means no timeout. Defaults to 60-second timeout.

Raises:

DaytonaError - If timeout is negative or the operation fails/times out.

Resources

@dataclass
class Resources()

Resources configuration for Sandbox.

Attributes:

cpu int | None - Number of CPU cores to allocate.
memory int | None - Amount of memory in GiB to allocate.
disk int | None - Amount of disk space in GiB to allocate.
gpu int | None - Number of GPUs to allocate.
gpu_type GpuType | list[GpuType] | None - Preferred GPU type for the Sandbox.

Example:

resources = Resources(
    cpu=2,
    memory=4,  # 4GiB RAM
    disk=20,   # 20GiB disk
    gpu=1,
    gpu_type=GpuType.H100,
)
params = CreateSandboxFromImageParams(
    image=Image.debian_slim("3.12"),
    language="python",
    resources=resources
)

ListSandboxesQuery

@dataclass
class ListSandboxesQuery()

Query parameters for filtering and sorting when listing Sandboxes.

Attributes:

limit - Per-page fetch size. Does NOT limit the total number of Sandboxes returned.
id - Filter by ID prefix (case-insensitive).
name - Filter by name prefix (case-insensitive).
labels - Filter by labels.
states - Filter by states.
snapshots - Filter by snapshot names.
targets - Filter by targets.
min_cpu - Filter by minimum CPU.
max_cpu - Filter by maximum CPU.
min_memory_gib - Filter by minimum memory in GiB.
max_memory_gib - Filter by maximum memory in GiB.
min_disk_gib - Filter by minimum disk space in GiB.
max_disk_gib - Filter by maximum disk space in GiB.
is_public - Filter by public status.
is_recoverable - Filter by recoverable status.
created_at_after datetime - Include sandboxes created after this timestamp.
created_at_before datetime - Include sandboxes created before this timestamp.
last_activity_after datetime - Include sandboxes with last activity after this timestamp.
last_activity_before datetime - Include sandboxes with last activity before this timestamp.
sort - Field to sort by.
order - Sort direction.

SandboxMetrics

@dataclass
class SandboxMetrics()

A single point-in-time sample of historical Sandbox resource usage.

Each instance corresponds to one aggregation bucket returned by the telemetry backend. Use :meth:Sandbox.get_metrics to fetch a time-ordered list of these, or :meth:Sandbox.get_metrics_latest for the current sample.

Attributes:

cpu_count int - Number of CPU cores allocated to the Sandbox.
cpu_used_pct float - CPU utilization as a percentage of the allocated limit.
disk_total int - Total disk space in bytes.
disk_used int - Used disk space in bytes.
mem_total int - Total memory in bytes.
mem_used int - Used memory in bytes.
mem_cache int - Memory used by the page cache in bytes.
timestamp datetime - Timestamp of this sample.

sandbox_metrics_from_system_metrics

def sandbox_metrics_from_system_metrics(
        system_metrics: _SystemMetrics) -> SandboxMetrics

Converts a live daemon SystemMetrics snapshot into a SandboxMetrics sample.

pivot_sandbox_metrics

def pivot_sandbox_metrics(
    points: Iterable[tuple[str | None, str | None, float | None]]
) -> list[SandboxMetrics]

Buckets (metric_name, timestamp, value) triples by timestamp into SandboxMetrics samples.

Sandbox

env: dict[str, str] | None

network_block_all: bool | None

Sandbox.__init__

Sandbox.refresh_data

Sandbox.get_user_home_dir

Sandbox.get_work_dir

Sandbox.get_metrics_latest

Sandbox.get_metrics

Sandbox.create_lsp_server

Sandbox.set_labels

Sandbox.start

Sandbox.recover

Sandbox.stop

Sandbox.delete

Sandbox.wait_for_sandbox_start

Sandbox.wait_for_sandbox_stop

Sandbox.set_autostop_interval

Sandbox.set_auto_pause_interval

Sandbox.set_auto_archive_interval

Sandbox.set_auto_delete_interval

Sandbox.update_network_settings

Sandbox.update_secrets

Sandbox.update_env

Sandbox.get_preview_link

Sandbox.create_signed_preview_url

Sandbox.expire_signed_preview_url

Sandbox.archive

Sandbox.resize

Sandbox.wait_for_resize_complete

Sandbox.create_ssh_access

Sandbox.revoke_ssh_access

Sandbox.validate_ssh_access

Sandbox.refresh_activity

Sandbox.pause

Resources

ListSandboxesQuery

SandboxMetrics

sandbox_metrics_from_system_metrics

pivot_sandbox_metrics

env: `dict[str, str] | None`

network_block_all: `bool | None`

Sandbox.init