AsyncSandbox

python

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 - Daytona snapshot used to create the Sandbox.
user str - OS user running in the Sandbox.
env dict[str, str] - Environment variables set in the Sandbox.
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 - Current state of the Sandbox (e.g., "started", "stopped").
error_reason str - Error message if Sandbox is in error state.
recoverable bool - Whether the Sandbox error is recoverable.
backup_state SandboxBackupStateEnum - Current state of Sandbox backup.
backup_created_at str - When the backup was created.
auto_stop_interval int - Auto-stop interval in minutes.
auto_archive_interval int - Auto-archive interval in minutes.
auto_delete_interval int - Auto-delete interval in minutes.
volumes list[str] - Volumes attached to the Sandbox.
build_info str - Build information for the Sandbox if it was created from dynamic build.
created_at str - When the Sandbox was created.
updated_at str - When the Sandbox was last updated.
last_activity_at str - When the Sandbox last had activity.
network_block_all bool - Whether to block all network access for the Sandbox.
network_allow_list str - Comma-separated list of allowed CIDR network addresses for the Sandbox.

AsyncSandbox.refresh_data

python

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

Refreshes the Sandbox data from the API.

Example:

python

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

python

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

python

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

AsyncSandbox.get_work_dir

python

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

python

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

AsyncSandbox.create_lsp_server

python

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

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:

python

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

AsyncSandbox.set_labels

python

@intercept_errors(message_prefix="Failed to set labels: ")
@with_instrumentation()
async def set_labels(labels: dict[str, str]) -> 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.

Returns:

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

Example:

python

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

AsyncSandbox.start

python

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

python

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

AsyncSandbox.recover

python

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

python

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

AsyncSandbox.stop

python

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

python

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

AsyncSandbox.delete

python

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

AsyncSandbox.wait_for_sandbox_start

python

@intercept_errors(
    message_prefix="Failure during waiting for sandbox to start: ")
@with_timeout()
@with_instrumentation()
async 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

AsyncSandbox.wait_for_sandbox_stop

python

@intercept_errors(
    message_prefix="Failure during waiting for sandbox to stop: ")
@with_timeout()
@with_instrumentation()
async 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.

AsyncSandbox.set_autostop_interval

python

@intercept_errors(message_prefix="Failed to set auto-stop interval: ")
@with_instrumentation()
async def set_autostop_interval(interval: int) -> 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.

Raises:

DaytonaValidationError - If interval is negative

Example:

python

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

AsyncSandbox.set_auto_archive_interval

python

@intercept_errors(message_prefix="Failed to set auto-archive interval: ")
@with_instrumentation()
async def set_auto_archive_interval(interval: int) -> 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.

Raises:

DaytonaValidationError - If interval is negative

Example:

python

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

AsyncSandbox.set_auto_delete_interval

python

@intercept_errors(message_prefix="Failed to set auto-delete interval: ")
@with_instrumentation()
async def set_auto_delete_interval(interval: int) -> 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.

Example:

python

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

AsyncSandbox.update_network_settings

python

@intercept_errors(message_prefix="Failed to update network settings: ")
@with_instrumentation()
async def update_network_settings(
        *,
        network_block_all: bool | None = None,
        network_allow_list: str | 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.

Raises:

DaytonaValidationError - If neither argument is set.

Example:

python

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

AsyncSandbox.get_preview_link

python

@intercept_errors(message_prefix="Failed to get preview link: ")
@with_instrumentation()
async def get_preview_link(port: int) -> 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.

Returns:

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

Example:

python

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

AsyncSandbox.create_signed_preview_url

python

@intercept_errors(message_prefix="Failed to create signed preview url: ")
async def create_signed_preview_url(
        port: int,
        expires_in_seconds: int | 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.

Returns:

SignedPortPreviewUrl - The response object for the signed preview url.

AsyncSandbox.expire_signed_preview_url

python

@intercept_errors(message_prefix="Failed to expire signed preview url: ")
async def expire_signed_preview_url(port: int, token: str) -> 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.

AsyncSandbox.archive

python

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

AsyncSandbox.resize

python

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

Resizes the Sandbox resources.

Changes the CPU, memory, or disk allocation for the Sandbox. Hot resize (on running sandbox) only allows CPU/memory increases. Disk resize requires a stopped sandbox.

Arguments:

resources Resources - New resource configuration. Only specified fields will be updated.
- cpu: Number of CPU cores (minimum: 1). For hot resize, can only be increased.
- memory: Memory in GiB (minimum: 1). For hot resize, can only be increased.
- disk: Disk space in GiB (can only be increased, requires stopped sandbox).
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 (CPU/memory decrease on running sandbox).
DaytonaError - If disk resize attempted on running sandbox.
DaytonaError - If disk size decrease is attempted.
DaytonaError - If resize operation times out.
DaytonaError - If no resource changes are specified.

Example:

python

# Increase CPU/memory on running sandbox (hot resize)
await sandbox.resize(Resources(cpu=4, memory=8))

# Change disk (sandbox must be stopped)
await sandbox.stop()
await sandbox.resize(Resources(cpu=2, memory=4, disk=30))

AsyncSandbox.wait_for_resize_complete

python

@intercept_errors(
    message_prefix="Failure during waiting for resize to complete: ")
@with_timeout()
@with_instrumentation()
async 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.

AsyncSandbox.create_ssh_access

python

@intercept_errors(message_prefix="Failed to create SSH access: ")
@with_instrumentation()
async def create_ssh_access(
        expires_in_minutes: int | 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.

AsyncSandbox.revoke_ssh_access

python

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

Revokes an SSH access token for the sandbox.

Arguments:

token str - The token to revoke.

AsyncSandbox.validate_ssh_access

python

@intercept_errors(message_prefix="Failed to validate SSH access: ")
@with_instrumentation()
async def validate_ssh_access(token: str) -> SshAccessValidationDto

Validates an SSH access token for the sandbox.

Arguments:

token str - The token to validate.

AsyncSandbox.refresh_activity

python

@intercept_errors(message_prefix="Failed to refresh sandbox activity: ")
async def refresh_activity() -> 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.

Example:

python

await sandbox.refresh_activity()

AsyncPaginatedSandboxes

python

class AsyncPaginatedSandboxes(PaginatedSandboxesDto)

Represents a paginated list of Daytona Sandboxes.

Attributes:

items list[AsyncSandbox] - List of Sandbox instances in the current page.
total int - Total number of Sandboxes across all pages.
page int - Current page number.
total_pages int - Total number of pages available.

items: `list[AsyncSandbox]`

python

items = None

pyright: ignore[reportIncompatibleVariableOverride]

Resources

python

@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.

Example:

python

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

AsyncSandbox

AsyncSandbox

AsyncSandbox.refresh_data

AsyncSandbox.get_user_home_dir

AsyncSandbox.get_work_dir

AsyncSandbox.create_lsp_server

AsyncSandbox.set_labels

AsyncSandbox.start

AsyncSandbox.recover

AsyncSandbox.stop

AsyncSandbox.delete

AsyncSandbox.wait_for_sandbox_start

AsyncSandbox.wait_for_sandbox_stop

AsyncSandbox.set_autostop_interval

AsyncSandbox.set_auto_archive_interval

AsyncSandbox.set_auto_delete_interval

AsyncSandbox.update_network_settings

AsyncSandbox.get_preview_link

AsyncSandbox.create_signed_preview_url

AsyncSandbox.expire_signed_preview_url

AsyncSandbox.archive

AsyncSandbox.resize

AsyncSandbox.wait_for_resize_complete

AsyncSandbox.create_ssh_access

AsyncSandbox.revoke_ssh_access

AsyncSandbox.validate_ssh_access

AsyncSandbox.refresh_activity

AsyncPaginatedSandboxes

items: list[AsyncSandbox]

Resources

items: `list[AsyncSandbox]`