Sandbox

class Sandbox()

Serializable sandbox handle with process/fs/git/interpreter/pty namespaces.

Sandbox.init

def __init__(impl: AsyncSandbox, bridge: SyncBridge) -> None

Sandbox.id

@property
def id() -> str

Sandbox.name

@property
def name() -> str | None

Sandbox.state

@property
def state() -> Literal['queued', 'creating', 'starting', 'started', 'pausing', 'paused', 'stopping', 'stopped', 'destroying', 'destroyed', 'error', 'unknown']

Sandbox.image_build_id

@property
def image_build_id() -> str | None

Sandbox.image

@property
def image() -> ImageRef | None

Sandbox.snapshot

@property
def snapshot() -> SnapshotRef | None

Sandbox.target

@property
def target() -> str | None

Sandbox.region

@property
def region() -> Optional[str]

Sandbox.capabilities

@property
def capabilities() -> dict[str, str | int | float | bool | None | Sequence[str | int | float | bool | None | Sequence[JsonValue] | Mapping[str, JsonValue]] | Mapping[str, str | int | float | bool | None | Sequence[JsonValue] | Mapping[str, JsonValue]]]

Sandbox.labels

@property
def labels() -> Dict[str, str]

Sandbox.cpu

@property
def cpu() -> Optional[float]

Sandbox.cpu_max

@property
def cpu_max() -> Optional[int]

Sandbox.memory

@property
def memory() -> Optional[float]

Sandbox.memory_max

@property
def memory_max() -> Optional[float]

Sandbox.disk

@property
def disk() -> Optional[float]

Sandbox.disk_max

@property
def disk_max() -> Optional[float]

Sandbox.vm_class

@property
def vm_class() -> Optional[VmClass]

Sandbox.persistent

@property
def persistent() -> Optional[bool]

Sandbox.archived

@property
def archived() -> Optional[bool]

Sandbox.spot

@property
def spot() -> Optional[bool]

Sandbox.spot_evicted_at

@property
def spot_evicted_at() -> Optional[str]

Sandbox.lifecycle_policy

@property
def lifecycle_policy() -> Optional[SandboxLifecycle]

Sandbox.forked_from

@property
def forked_from() -> Optional[str]

Sandbox.reservation_id

@property
def reservation_id() -> Optional[str]

Sandbox.user

@property
def user() -> Optional[str]

Sandbox.error

@property
def error() -> Optional[str]

Sandbox.error_reason

@property
def error_reason() -> Optional[str]

Sandbox.access_token

@property
def access_token() -> str | None

Sandbox.access_token_expires_at

@property
def access_token_expires_at() -> str | None

Sandbox.toolbox_proxy_url

@property
def toolbox_proxy_url() -> str | None

Sandbox.archive

def archive() -> None

Archive a stopped persistent sandbox now, whatever its archive interval.

Sandbox.build_logs

def build_logs() -> str

Return retained build output as one-shot text, not a live follower.

Sandbox.create_access_token

def create_access_token(*,
                        operations: Optional[Sequence[str]] = None,
                        ports: Optional[Sequence[int]] = None,
                        ttl_seconds: Optional[int] = None) -> SandboxAccessToken

Mint a scoped, short-lived access token for THIS sandbox.

Sandbox.create_snapshot

def create_snapshot(name: str) -> Snapshot

Sandbox.entrypoint_logs

def entrypoint_logs() -> str

Return the sandbox entrypoint-session log as text.

Sandbox.exec

def exec(command: Optional[str] = None,
         *,
         argv: Optional[Sequence[str]] = None,
         cwd: Optional[str] = None,
         env: Optional[Mapping[str, str]] = None,
         user: Optional[str] = None,
         shell: Optional[str] = None,
         login: Optional[bool] = None,
         stdin: StdinMode = 'closed',
         timeout: Optional[float] = None,
         execution_timeout: Optional[float] = None,
         name: Optional[str] = None,
         terminal: Optional[TerminalSize] = None,
         keep_logs: Optional[KeepLogs] = None) -> ProcessResult

Run a command, wait for its shell to exit, and collect its output.

Sandbox.follow_build_logs

def follow_build_logs(*,
                      on_logs: _LogsCallback,
                      on_event: Optional[_EventCallback] = None,
                      cursor: Optional[str] = None,
                      timeout: Optional[float] = None) -> BuildLogFollowResult

Observe this sandbox's build without changing its execution lifetime.

Sandbox.get_network_policy

def get_network_policy() -> NetworkPolicyInfo

Sandbox.get_secrets

def get_secrets() -> SandboxSecretsInfo

Read this sandbox's attached secret names and their apply state (GET /sandboxes/{id}/secrets).

Sandbox.metrics

def metrics() -> SystemMetrics

Sandbox.pause

def pause(*, timeout: float = 60) -> None

Pause a persistent linux or macOS sandbox with its memory.

Sandbox.refresh_data

def refresh_data(*,
                 timeout: Optional[float] = None,
                 wait: SandboxWaitState | None = None,
                 wait_timeout_ms: int | None = None) -> None

Refresh sandbox fields from the control plane.

Sandbox.replace_secrets

def replace_secrets(*, secrets: Sequence[str], if_match: str) -> SandboxSecretsInfo

Replace the full set of project secrets attached to this sandbox (PUT /sandboxes/{id}/secrets).

Sandbox.reset_idle_timer

def reset_idle_timer() -> SandboxLifecycle

Reset this sandbox's idle timer (an explicit out-of-band keepalive).

Sandbox.reset_network_policy

def reset_network_policy(*, if_match: str) -> NetworkPolicyInfo

Sandbox.resume

def resume(*, timeout: float = 60) -> None

Resume a paused linux or macOS sandbox and wait for started.

Sandbox.rotate_signing_key

def rotate_signing_key() -> None

Rotate the sandbox's signing key; every pre-signed URL minted so far is retired.

Sandbox.run_code

def run_code(code: str,
             *,
             language: str = 'python',
             context: Optional[InterpreterContext] = None,
             isolated: bool = False,
             timeout: Optional[float] = None,
             cwd: Optional[str] = None,
             env: Optional[Mapping[str, str]] = None) -> InterpreterResult

Sandbox.set_labels

def set_labels(*, labels: Mapping[str, str]) -> Dict[str, str]

Replace the sandbox label set; pass {} to clear all labels.

Sandbox.snapshot_filesystem

def snapshot_filesystem(*,
                        name: Optional[str] = None,
                        idle: Optional[int] = None) -> Image

Snapshot this sandbox's filesystem as a new Image (POST /sandboxes/{id}/images).

Sandbox.start

def start(*, timeout: float = 60) -> None

Start a stopped sandbox, or resume a paused one, and wait for started.

Sandbox.to_json

def to_json() -> Dict[str, JsonValue]

The sandbox's data as JSON, without any toolbox URL; resume a stored sandbox with get(info["sandboxId"]).

Sandbox.update_env

def update_env(env: Optional[Mapping[str, str]] = None,
               *,
               unset: Sequence[str] = ()) -> None

Update SDK-managed environment entries for new processes, PTYs, and sessions.

Sandbox.update_lifecycle_policy

def update_lifecycle_policy(*,
                            timeout_seconds: Optional[int] = None,
                            on_timeout: Optional[LifecycleAction] = None,
                            idle_expiry_seconds: Optional[int] = None,
                            on_idle_timeout: Optional[LifecycleAction] = None,
                            wake_on_request: Optional[bool] = None,
                            archive_interval_seconds: Optional[int] = None) -> SandboxLifecycle

Update this sandbox's lifecycle policy; omitted knobs stay unchanged.

Sandbox.update_network_policy

def update_network_policy(*,
                          network_policy: NetworkPolicyInput,
                          if_match: str) -> NetworkPolicyInfo

Sandbox.wait

def wait(*, until: SandboxWaitState = 'started', timeout: Optional[float] = 60) -> Self

Wait for one public sandbox state and return self.

Sandbox.wait_for_state

def wait_for_state(states: Sequence[SandboxWaitState],
                   terminal_states: Sequence[SandboxState] = DEFAULT_SANDBOX_TERMINAL_STATES,
                   *,
                   timeout: Optional[float] = None) -> None

Wait until the sandbox reaches one of states.

Sandbox.computer_use

@property
def computer_use() -> ComputerUseService

Sandbox.docker

@property
def docker() -> DockerService

Docker Engine status inside the sandbox; see DockerService.

Sandbox.fs

@property
def fs() -> FileSystemService

Sandbox.git

@property
def git() -> GitService

Sandbox.interpreter

@property
def interpreter() -> InterpreterService

Sandbox.lsp

@property
def lsp() -> LspService

Sandbox.mac_boot_mode

@property
def mac_boot_mode() -> Optional[MacBootMode]

macOS only: how the sandbox came back from its last resume, or None.

Sandbox.ports

@property
def ports() -> PortsService

Sandbox.process

@property
def process() -> ProcessService

Sandbox.pty

@property
def pty() -> PtyService

Sandbox.raw_state

@property
def raw_state() -> str

Wire status string exactly as the server sent it.

AsyncSandbox

class AsyncSandbox()

Serializable sandbox handle with process/fs/git/interpreter/pty namespaces.

_experimental_gpu (abstract GPU count, 0 for non-GPU sandboxes) is experimental and may change or be removed without notice.

AsyncSandbox.init

def __init__(info: SandboxInfo,
             api: Optional[AsyncTransport],
             toolbox: Optional[AsyncTransport],
             *,
             toolbox_owner: Optional[AsyncTransport] = None,
             toolbox_url: Optional[str] = None,
             language: Optional[str] = None,
             access_token: Optional[str] = None,
             toolbox_base_url: Optional[str] = None,
             toolbox_token: Optional[str] = None,
             direct_toolbox_url: Optional[str] = None,
             request_timeout: Optional[float] = None,
             access_token_expires_at: Optional[str] = None,
             access_token_caller_supplied: Optional[bool] = None,
             hub: Optional[WaitHub] = None,
             hub_provider: Optional[Callable[[], Optional[WaitHub]]] = None) -> None

AsyncSandbox.raw_state

@property
def raw_state() -> str

Wire status string exactly as the server sent it.

Informational only — the SDK never branches on this value. Use state for all flow-control logic; raw_state is useful for logging when state == "unknown" (the SDK predates the server's value).

AsyncSandbox.from_api

@classmethod
def from_api(vm: SandboxDto | SandboxListItem | Mapping[str, JsonValue],
             api: Optional[AsyncTransport],
             toolbox: Optional[AsyncTransport],
             *,
             toolbox_owner: Optional[AsyncTransport] = None,
             toolbox_url: Optional[str] = None,
             language: Optional[str] = None,
             access_token: Optional[str] = None,
             toolbox_base_url: Optional[str] = None,
             toolbox_token: Optional[str] = None,
             direct_toolbox_url: Optional[str] = None,
             request_timeout: Optional[float] = None,
             access_token_expires_at: Optional[str] = None,
             access_token_caller_supplied: Optional[bool] = None,
             hub: Optional[WaitHub] = None,
             hub_provider: Optional[Callable[[], Optional[WaitHub]]] = None) -> AsyncSandbox

Create a sandbox handle from a control-plane DTO.

An explicitly passed access_token is treated as caller-supplied (never silently replaced by a minted one) unless access_token_caller_supplied=False marks it as the SDK-owned create-response credential.

A toolbox_proxy_url inside vm is ignored unless the SDK's own refresh/fork paths mark vm as a fresh control-plane response, so stored data never chooses where a credential goes (#3398). Pass toolbox or toolbox_url to set the toolbox explicitly — the toolbox credential goes there, so pass only a URL you trust.

AsyncSandbox.mac_boot_mode

@property
def mac_boot_mode() -> Optional[MacBootMode]

macOS only: how the sandbox came back from its last resume, or None.

cold_after_restore_failure means the memory could not be restored and the Mac booted the disk; error_reason says why.

AsyncSandbox.process

@property
def process() -> AsyncProcessService

AsyncSandbox.fs

@property
def fs() -> AsyncFileSystemService

AsyncSandbox.git

@property
def git() -> AsyncGitService

AsyncSandbox.interpreter

@property
def interpreter() -> AsyncInterpreterService

AsyncSandbox.pty

@property
def pty() -> AsyncPtyService

AsyncSandbox.computer_use

@property
def computer_use() -> AsyncComputerUseService

AsyncSandbox.docker

@property
def docker() -> AsyncDockerService

Docker Engine status inside the sandbox; see AsyncDockerService.

AsyncSandbox.ports

@property
def ports() -> AsyncPortsService

AsyncSandbox.lsp

@property
def lsp() -> AsyncLspService

AsyncSandbox.metrics

async def metrics() -> SystemMetrics

AsyncSandbox.exec

async def exec(command: Optional[str] = None,
               *,
               argv: Optional[Sequence[str]] = None,
               cwd: Optional[str] = None,
               env: Optional[Mapping[str, str]] = None,
               user: Optional[str] = None,
               shell: Optional[str] = None,
               login: Optional[bool] = None,
               stdin: StdinMode = 'closed',
               timeout: Optional[float] = None,
               execution_timeout: Optional[float] = None,
               name: Optional[str] = None,
               terminal: Optional[TerminalSize] = None,
               keep_logs: Optional[KeepLogs] = None) -> ProcessResult

Run a command, wait for its shell to exit, and collect its output.

A convenience alias for process.run — identical behaviour, same parameters, same return value.

Shell selection. Passing a string command runs it through the sandbox shell: bash when the image has it, else sh. Pass shell= to pin another interpreter, and quote globs and brackets (pip install -e '.[test]') so the command means the same under any shell. Use argv= to bypass the shell entirely, which is the safe form for untrusted arguments. For persistent shell state, use process.create_session.

Background processes. The call returns when the shell exits. If the command launches a background child that holds output open (e.g. python3 -m http.server 8000 &), the daemon waits at most ~2 seconds for output to drain and then returns; output the child writes later is not part of the result. For a long-running server use process.start, which returns a ProcessHandle immediately (logs, wait, kill). Alternatively redirect: nohup cmd > server.log 2>&1 &.

:param command: Shell command string; mutually exclusive with argv. :param argv: Argument vector for shell-free execution. :param cwd: Working directory inside the sandbox. :param env: Extra environment variables merged into the process environment. :param shell: Shell binary to use (e.g. "bash"); overrides auto-detection. :param timeout: Caller wait budget in seconds. Omit to wait until the process ends. Does not kill the process; use execution_timeout for that. :param execution_timeout: Server-side deadline in seconds. The daemon kills the process tree when this expires. :returns: daytona.v2.types.ProcessResult with stdout, stderr, output, exit_code, and reason.

AsyncSandbox.run_code

async def run_code(code: str,
                   *,
                   language: str = 'python',
                   context: Optional[AsyncInterpreterContext] = None,
                   isolated: bool = False,
                   timeout: Optional[float] = None,
                   cwd: Optional[str] = None,
                   env: Optional[Mapping[str, str]] = None) -> InterpreterResult

AsyncSandbox.to_json

def to_json() -> Dict[str, JsonValue]

The sandbox's data as JSON, without any toolbox URL; resume a stored sandbox with get(info["sandboxId"]).

AsyncSandbox.set_labels

async def set_labels(*, labels: Mapping[str, str]) -> Dict[str, str]

Replace the sandbox label set; pass {} to clear all labels.

AsyncSandbox.entrypoint_logs

async def entrypoint_logs() -> str

Return the sandbox entrypoint-session log as text.

AsyncSandbox.update_env

async def update_env(env: Optional[Mapping[str, str]] = None,
                     *,
                     unset: Sequence[str] = ()) -> None

Update SDK-managed environment entries for new processes, PTYs, and sessions.

Processes, PTYs, and sessions started after this call inherit the updated environment. Running processes and already-running session kernels keep their current environment unchanged. unset removes only values previously set through update_env(); image-level environment entries remain untouched.

AsyncSandbox.refresh_data

async def refresh_data(*,
                       timeout: Optional[float] = None,
                       wait: SandboxWaitState | None = None,
                       wait_timeout_ms: int | None = None) -> None

Refresh sandbox fields from the control plane.

AsyncSandbox.wait_for_state

async def wait_for_state(states: Sequence[SandboxWaitState],
                         terminal_states: Sequence[SandboxState] = DEFAULT_SANDBOX_TERMINAL_STATES,
                         *,
                         timeout: Optional[float] = None) -> None

Wait until the sandbox reaches one of states.

timeout is the caller wait budget in seconds; None and 0 wait unbounded. If the sandbox reaches a terminal state before any target state, a typed conflict error is raised with the observed public sandbox state attached as error.state.

AsyncSandbox.wait

async def wait(*,
               until: SandboxWaitState = 'started',
               timeout: Optional[float] = 60) -> Self

Wait for one public sandbox state and return self.

timeout is a caller wait budget in seconds. The default is 60; None and 0 wait without a deadline. Timeout raises RequestTimeoutError and a terminal state before until raises SandboxTerminalStateError.

AsyncSandbox.start

async def start(*, timeout: float = 60) -> None

Start a stopped sandbox, or resume a paused one, and wait for started.

AsyncSandbox.pause

async def pause(*, timeout: float = 60) -> None

Pause a persistent linux or macOS sandbox with its memory.

Linux returns once the pause is accepted (pausing). macOS waits up to timeout for paused and raises SandboxTerminalStateError if the pause fails. A paused macOS sandbox keeps its Mac slot but does not keep its reservation renewing.

AsyncSandbox.resume

async def resume(*, timeout: float = 60) -> None

Resume a paused linux or macOS sandbox and wait for started.

A macOS resume the Mac cannot finish ends stopped; this then raises SandboxTerminalStateError.

AsyncSandbox.stop

async def stop() -> None

Warm-stop a persistent sandbox.

AsyncSandbox.archive

async def archive() -> None

Archive a stopped persistent sandbox now, whatever its archive interval.

Its disk moves to object storage in the background; archived turns true once that completes, and start restores the disk first. Archiving an archived sandbox does nothing.

AsyncSandbox.fork

async def fork(*,
               name: Optional[str] = None,
               memory: Optional[bool] = None,
               timeout: Optional[float] = None) -> AsyncSandbox

Fork this sandbox.

By default the fork continues from the source's memory (running processes included). memory=False forks only the disk: an instant copy-on-write clone, after which the fork boots fresh. A stopped sandbox is always forked disk-only. Only a fork of a RUNNING sandbox is started automatically; a fork of a paused source rests paused (memory fork, call resume()) or stopped (memory=False), and a fork of a stopped source rests stopped — call start() on those.

A macOS fork copies the disk only: omit memory or pass memory=False (memory=True is refused with NOT_SUPPORTED_FOR_CLASS). A fork of a running macOS sandbox boots with a fresh machine identity; a fork of a paused or stopped one rests stopped. The fork is made on the Mac that keeps the source when that Mac has room for the fork's size. Otherwise, in a region with macOS snapshots configured, the source's disk is copied through an anonymous image to another Mac of the organization, and the fork waits for room there as a create does. Without macOS snapshots in the region, or for a paused source on a full Mac, the server answers NO_FREE_SLOT.

With timeout (seconds; 0 waits without a deadline), wait for the state the fork settles in: started for a fork of a running Linux sandbox, paused or stopped for the other Linux forks, and started or stopped for a macOS fork. Without it, return as soon as the server accepts the fork.

AsyncSandbox.delete

async def delete() -> None

Delete the sandbox.

AsyncSandbox.update_lifecycle_policy

async def update_lifecycle_policy(*,
                                  timeout_seconds: Optional[int] = None,
                                  on_timeout: Optional[LifecycleAction] = None,
                                  idle_expiry_seconds: Optional[int] = None,
                                  on_idle_timeout: Optional[LifecycleAction] = None,
                                  wake_on_request: Optional[bool] = None,
                                  archive_interval_seconds: Optional[int] = None) -> SandboxLifecycle

Update this sandbox's lifecycle policy; omitted knobs stay unchanged.

timeout_seconds re-anchors the deadline from now (>= 1; the timeout cannot be disabled). idle_expiry_seconds=DISABLED clears the idle pair; arming it on a sandbox with no idle policy requires on_idle_timeout. archive_interval_seconds (linux persistent) takes 60 to 2592000, or 0 for the maximum.

Setting either action to "delete" — or touching a pair whose stored or resulting action is "delete" — requires the API key to hold delete:sandboxes in addition to write:sandboxes.

AsyncSandbox.reset_idle_timer

async def reset_idle_timer() -> SandboxLifecycle

Reset this sandbox's idle timer (an explicit out-of-band keepalive).

For work the platform cannot see: bumps the sandbox's activity clock (last_activity_at, attributed server-side to the api source), which restarts the idle countdown — idle_timeout_at re-anchors to now + idle_expiry_seconds. The wall-clock timeout_at is NOT affected. Succeeds whether or not an idle timeout is armed (an unarmed sandbox echoes idle_timeout_at=None), and in any state — a never-started sandbox already carries its creation-time activity stamp, which the reset advances.

The echo is the full post-reset lifecycle, the same shape update_lifecycle_policy returns. Advance-only: a newer concurrent activity bump keeps the clock, and what comes back is the state that won.

AsyncSandbox.get_network_policy

async def get_network_policy() -> NetworkPolicyInfo

AsyncSandbox.update_network_policy

async def update_network_policy(*,
                                network_policy: NetworkPolicyInput,
                                if_match: str) -> NetworkPolicyInfo

AsyncSandbox.reset_network_policy

async def reset_network_policy(*, if_match: str) -> NetworkPolicyInfo

AsyncSandbox.get_secrets

async def get_secrets() -> SandboxSecretsInfo

Read this sandbox's attached secret names and their apply state (GET /sandboxes/{id}/secrets).

Returns names and revisions only, never values. etag is the If-Match value for replace_secrets; status is pending until the sandbox has applied desired_revision.

AsyncSandbox.replace_secrets

async def replace_secrets(*,
                          secrets: Sequence[str],
                          if_match: str) -> SandboxSecretsInfo

Replace the full set of project secrets attached to this sandbox (PUT /sandboxes/{id}/secrets).

secrets names project secrets; unchanged names keep their placeholders. if_match is the etag of the last read; a stale one raises PreconditionFailedError. The change applies asynchronously: poll get_secrets until status is applied. Running processes keep their environment; processes started afterwards see the new names.

AsyncSandbox.snapshot_filesystem

async def snapshot_filesystem(*,
                              name: Optional[str] = None,
                              idle: Optional[int] = None) -> Image

Snapshot this sandbox's filesystem as a new Image (POST /sandboxes/{id}/images).

The result boots new sandboxes (daytona.create(image.id)), like Modal's snapshot_filesystem(); the sandbox keeps running. A macOS sandbox must be persistent and stopped; it cannot start until the snapshot is ready.

name makes the image named and permanent. idle (seconds) is the idle-retention window of an ANONYMOUS capture: it is deleted once that long has passed without a sandbox being created from it (every create restarts the clock). Same rule as images.build: omitted or -1 ⇒ the server maximum (7 days by default); above it ⇒ 400. Promote the image to keep it. idle with name is a 400.

AsyncSandbox.create_snapshot

async def create_snapshot(name: str) -> Snapshot

AsyncSandbox.build_logs

async def build_logs() -> str

Return retained build output as one-shot text, not a live follower.

The body includes a state line and the currently available build tail. The log belongs to the build: an adopted build returns the original build's output, and a build that failed before the sandbox was placed still returns its failure. A sandbox with no image build (no server-side image_build_id, for example a registry image) raises NotFoundError. Before a capture is assigned, the response can contain only build state. An expired or unreachable capture can raise BUILD_LOG_UNAVAILABLE; retained-tail truncation is indicated in the text. Discovery selects the owning build-log service. The one-shot request returns its current retained output as text. Use follow_build_logs for live output and completeness metadata.

AsyncSandbox.follow_build_logs

async def follow_build_logs(*,
                            on_logs: _LogsCallback,
                            on_event: Optional[_EventCallback] = None,
                            cursor: Optional[str] = None,
                            timeout: Optional[float] = None) -> BuildLogFollowResult

Observe this sandbox's build without changing its execution lifetime.

on_logs receives decoded output; optional on_event receives each typed BuildLogEvent. Either callback may return an awaitable, which is awaited before the next event. timeout (seconds) bounds this observation only; cancelling the awaiting task closes the stream, not the build. Discovery failures, including a 404 for a sandbox with no image build, raise BuildLogInterruptedError with the HTTP status and last cursor. They do not fall back to another log source.

AsyncSandbox.create_access_token

async def create_access_token(*,
                              operations: Optional[Sequence[str]] = None,
                              ports: Optional[Sequence[int]] = None,
                              ttl_seconds: Optional[int] = None) -> SandboxAccessToken

Mint a scoped, short-lived access token for THIS sandbox.

The token authorizes the sandbox data plane (toolbox, SSH, desktop, private previews) and the self-service control routes, for exactly the granted operations and ports — hand it to a collaborator, a CI job, or a browser instead of a project API key.

operations is the sandbox-operation vocabulary (toolbox, toolbox:exec, toolbox:fs, toolbox:git, toolbox:lsp, desktop, ssh, sandbox:stop, sandbox:pause, sandbox:delete); omitted means the minter's full grantable set, and [] is a valid ports-only grant. ports names the private-preview ports the token may reach (omitted = all, [] = none). ttl_seconds overrides the deployment's default lifetime, capped server-side; an unknown operation or an over-cap TTL is a 400, never a silent narrowing. The token cannot be refreshed and cannot mint further credentials — mint a fresh one here instead.

AsyncSandbox.rotate_signing_key

async def rotate_signing_key() -> None

Rotate the sandbox's signing key; every pre-signed URL minted so far is retired.

Every pre-signed URL minted so far stops working within ~30 s; new URLs from presigned_download_url / presigned_upload_url use the new key. The key itself is never returned.

One class-blind route (/sandboxes) like the sign route; windows sandboxes have no toolbox and raise UNSUPPORTED_OPERATION before any request. Like minting, a handle on a direct-daemon toolbox_url is refused locally: nothing on that path could verify a signature, so there is nothing a rotation would retire.

SandboxEventsConfig

@dataclass(frozen=True)
class SandboxEventsConfig()

Configuration for the sandbox-state events hub.

enabled — set to False (or DAYTONA_SANDBOX_EVENTS=0) to fall back to long-poll for every wait. reconcile_interval is in seconds (0 / None disables the timer). idle_close (seconds) closes idle sockets; None keeps them open indefinitely.

Attributes:

enabled bool = True
reconcile_interval Optional[float] = 60.0
idle_close Optional[float] = None

SandboxSecretsInfo

@dataclass(frozen=True)
class SandboxSecretsInfo()

Attributes:

secrets List[str]
desired_revision int
etag str
http_status int
applied_revision Optional[int] = None
status Optional[str] = None
error Optional[str] = None
capture_status Optional[str] = None
capture_unresolved_count Optional[int] = None

SandboxInfo

@dataclass(frozen=True)
class SandboxInfo()

Serializable sandbox DTO.

Attributes:

id str
name Optional[str] = None
state SandboxState = 'unknown'
image Optional[ImageRef] = None
target Optional[str] = None
capabilities JsonObject = field(default_factory=dict)
snapshot Optional[SnapshotRef] = None
image_build_id Optional[str] = None
region Optional[str] = field(default=None, kw_only=True)
labels Dict[str, str] = field(default_factory=dict, kw_only=True)
cpu Optional[float] = field(default=None, kw_only=True)
cpu_max Optional[int] = field(default=None, kw_only=True)
gpu int = field(default=0, kw_only=True)
memory Optional[float] = field(default=None, kw_only=True)
memory_max Optional[float] = field(default=None, kw_only=True)
disk Optional[float] = field(default=None, kw_only=True)
disk_max Optional[float] = field(default=None, kw_only=True)
vm_class Optional[VmClass] = field(default=None, kw_only=True)
persistent Optional[bool] = field(default=None, kw_only=True)
archived Optional[bool] = field(default=None, kw_only=True)
spot Optional[bool] = field(default=None, kw_only=True)
spot_evicted_at Optional[str] = field(default=None, kw_only=True)
lifecycle_policy Optional[SandboxLifecycle] = field(default=None, kw_only=True)
forked_from Optional[str] = field(default=None, kw_only=True)
reservation_id Optional[str] = field(default=None, kw_only=True)
user Optional[str] = field(default=None, kw_only=True)
error Optional[str] = field(default=None, kw_only=True)

SandboxInfo.to_json

def to_json() -> Dict[str, JsonValue]

Return a JSON-safe sandbox-info payload.

SandboxInfo.from_json

@classmethod
def from_json(value: Mapping[str, JsonValue]) -> Self

Rehydrate sandbox info from to_json output.

SandboxLifecycle

@dataclass(frozen=True)
class SandboxLifecycle()

Lifecycle policy as the control plane reports it.

timeout_seconds is the stored re-arm budget (echoed, unlike the old write-only TTL anchor); timeout_at is the current absolute deadline it derives. idle_timeout_at is when on_idle_timeout becomes eligible to fire — last_activity_at + idle_expiry_seconds — and any activity (traffic, SSH, a non-PTY process or code execution started through the process API that is still running — exec, process.start, run_code and interpreter cells included — or AsyncSandbox.reset_idle_timer) pushes it; None when the idle pair is not armed or the sandbox has never been active. timeout_at, idle_timeout_at, last_activity_at and last_activity_source are server-derived and read-only. An action the SDK does not know yet (a newer server) is passed through as its wire string. archive_interval_seconds is None for a sandbox that is never archived (not linux persistent).

Attributes:

timeout_seconds Optional[int] = None
on_timeout Optional[str] = None
timeout_at Optional[str] = None
idle_expiry_seconds Optional[int] = None
on_idle_timeout Optional[str] = None
idle_timeout_at Optional[str] = None
wake_on_request bool = False
last_activity_at Optional[str] = None
last_activity_source Optional[str] = None
archive_interval_seconds Optional[int] = None

PreviewEndpoint

@dataclass(frozen=True)
class PreviewEndpoint()

A sandbox HTTP preview endpoint.

Attributes:

port int
public bool
url str
created_at Optional[str] = None

PreviewLink

@dataclass(frozen=True)
class PreviewLink()

Preview URL plus an access token for one in-VM port.

Send token in the X-Daytona-Preview-Token header to reach a private endpoint; without a credential the proxy answers 401. When token is a sandbox access token (a JWT) it also works as Authorization: Bearer or ?rlp_token=; the deployment's legacy HMAC token works only in the header. Public endpoints set token to "" and need no credential. expires_at (RFC 3339) is set when the token's expiry is known, else None.

Example — curl a private endpoint::

link = await sandbox.ports.preview_link(8080)

curl -H "X-Daytona-Preview-Token: <link.token>" <link.url>

For a shareable URL that works in a browser without extra headers, use daytona.v2.ports.AsyncPortsService.signed_preview_link instead.

Attributes:

url str
token str
expires_at Optional[str] = None

SignedPreviewLink

@dataclass(frozen=True)
class SignedPreviewLink()

Self-contained signed URL for one in-VM port.

The token is embedded in the hostname — no extra headers or credentials are needed. The link expires at expires_at (RFC 3339). Revoke it early with daytona.v2.ports.AsyncPortsService.expire_signed_preview_link.

Attributes:

url str
token str
expires_at Optional[str] = None

SandboxAccessToken

@dataclass(frozen=True)
class SandboxAccessToken()

A short-lived per-sandbox access token (POST …/access-token).

access_token is a bearer for the sandbox data plane (toolbox, SSH, desktop, private previews) and for the self-service control routes named by operations (sandbox:stop / sandbox:pause / sandbox:delete). It expires at expires_at (RFC 3339) and cannot be refreshed — mint a fresh one with daytona.v2.sandbox.AsyncSandbox.create_access_token instead. ports is the granted private-preview port set; None means every port.

Attributes:

access_token str
token_type str
expires_at str
operations Sequence[str]
ports Optional[Sequence[int]] = None

SandboxSearchFilters

@dataclass(frozen=True, kw_only=True)
class SandboxSearchFilters()

The GET /sandboxes/search filters shared by Daytona.search() and Daytona.list().

status, vm_class and region take a single value or a list; lists are joined with commas on the wire. labels is sent as a JSON object string (containment match); timestamp starts are inclusive and ends are exclusive.

Every filter is keyword-only, so subclasses that predate the search index (ListSandboxesQuery) keep their original positional parameters.

Attributes:

q Optional[str] = None
status Optional[Sequence[str]] = None
vm_class Optional[Union[VmClass, Sequence[VmClass]]] = None
region Optional[Sequence[str]] = None
image_ref Optional[str] = None
image_ref_prefix Optional[str] = None
labels Optional[Mapping[str, str]] = None
spot Optional[bool] = None
forked_from Optional[str] = None
min_vcpus Optional[int] = None
max_vcpus Optional[int] = None
min_memory_mib Optional[int] = None
max_memory_mib Optional[int] = None
min_disk_mib Optional[int] = None
max_disk_mib Optional[int] = None
created_start_at Optional[SearchTimestamp] = None
created_end_at Optional[SearchTimestamp] = None
updated_start_at Optional[SearchTimestamp] = None
updated_end_at Optional[SearchTimestamp] = None
last_activity_start_at Optional[SearchTimestamp] = None
last_activity_end_at Optional[SearchTimestamp] = None
sort Optional[SearchSort] = None
order Optional[SearchOrder] = None

SystemMetrics

SystemMetrics = _gen.toolbox.Metrics

SandboxWaitState

SandboxWaitState = Literal['queued', 'starting', 'started', 'pausing', 'paused', 'stopping', 'stopped', 'destroying', 'destroyed']

MacBootMode

MacBootMode = Union[Literal['restored', 'cold_after_restore_failure'], str]

On this page

Computersfor Agents