AsyncSandbox | Daytona

AsyncSandbox

@with_events

class AsyncSandbox(SandboxDto)

Represents a Daytona Sandbox.

Attributes:

• fs AsyncFileSystem - File system operations interface.
• git AsyncGit - Git operations interface.
• process AsyncProcess - Process execution interface.
• computer_use AsyncComputerUse - Computer use operations interface for desktop automation.
• code_interpreter AsyncCodeInterpreter - 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.
• spot bool - Whether this is a spot GPU Sandbox. Spot Sandboxes may be instantly terminated to free capacity for on-demand GPU Sandboxes.
• spot_evicted_at str | None - When the Sandbox was evicted by spot preemption.
• queue_timed_out_at str | None - When the Sandbox was destroyed because it waited too long for a runner.
• gpu_type GpuType | None - The GPU type assigned 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”).
• desired_state SandboxDesiredState | None - The desired state of the Sandbox.
• 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.
• auto_destroy_at str | None - When the Sandbox will be automatically destroyed (only set when a TTL is configured).
• queue_timeout int | None - Minutes to wait for runner assignment before Sandbox creation is cancelled.
• 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).
• kvm bool | None - Whether the sandbox exposes KVM (/dev/kvm) to its guest (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).
• outbound_proxy_url str | None - Outbound proxy URL to route the Sandbox HTTP(S) traffic through. Applied via the HTTP(S)_PROXY environment variables; combine with domain_allow_list for unbypassable network-layer enforcement. (not returned by list results; call refresh_data() on each item to populate).
• sandbox_class str | None - The class of the Sandbox.
• warm_pool_id str | None - ID of the warm pool this Sandbox waits in; set only while it is an unclaimed member.
• daemon_version str | None - The version of the daemon running in the Sandbox.
• otel_endpoint_override str | None - OTel collector endpoint override for this Sandbox. When set, Sandbox OTel data is sent to this endpoint instead of the default collector and is not available in the Daytona analytics API or dashboard (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

network_block_all: bool | None

network_block_all = None

kvm: bool | None

kvm = None

AsyncSandbox.init

def __init__(sandbox_dto: SandboxDto | SandboxListItem,
             toolbox_api: ApiClient,
             sandbox_api: SandboxApi,
             language: str,
             subscription_manager: AsyncEventSubscriptionManager,
             pool_tracker: AsyncPoolSaturationTracker | None = None,
             analytics_api_url_provider: Callable[[], Awaitable[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.
• language str - Language code for the Sandbox code_run.
• subscription_manager AsyncEventSubscriptionManager - for real-time updates.
• pool_tracker AsyncPoolSaturationTracker | None - Tracker for connection pool saturation.

AsyncSandbox.refresh_data

@intercept_errors(message_prefix="Failed to refresh sandbox data: ")
@with_instrumentation()
async 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:

await sandbox.refresh_data()

print(f"Sandbox {sandbox.id}:")

print(f"State: {sandbox.state}")

print(f"Resources: {sandbox.cpu} CPU, {sandbox.memory} GiB RAM")

AsyncSandbox.get_user_home_dir

@intercept_errors(message_prefix="Failed to get user home directory: ")
@with_instrumentation()
async 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 = await sandbox.get_user_home_dir()

print(f"Sandbox user home: {user_home_dir}")

AsyncSandbox.get_work_dir

@intercept_errors(message_prefix="Failed to get working directory path: ")
@with_instrumentation()
async 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 = await sandbox.get_work_dir()

print(f"Sandbox working directory: {work_dir}")

AsyncSandbox.get_metrics_latest

@intercept_errors(message_prefix="Failed to get sandbox metrics: ")
@with_instrumentation()
async 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.

AsyncSandbox.get_metrics

@intercept_errors(message_prefix="Failed to get sandbox metrics: ")
@with_instrumentation()
async 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.