---
title: "AsyncSandbox"
hideTitleOnPage: true
---

## 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 | 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_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).
- `toolbox_proxy_url` _str_ - The toolbox proxy URL for the Sandbox.

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

```python
env = None
```

pyright: ignore[reportRedeclaration]

##### network\_block\_all: `bool | None`

```python
network_block_all = None
```

pyright: ignore[reportRedeclaration]

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


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

## ListSandboxesQuery

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

