Sandbox

class Sandbox()

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

_experimental_gpu (abstract GPU count, 0 for non-GPU sandboxes) and _experimental_windows_image (golden Windows base image, None for Linux) are experimental and may change or be removed without notice.

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

Sandbox.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).

Sandbox.from_api

@classmethod
def from_api(vm: VmDetail | VmPageRow | 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) -> Sandbox

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.

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

Sandbox.process

@property
def process() -> ProcessService

Sandbox.fs

@property
def fs() -> FileSystemService

Sandbox.git

@property
def git() -> GitService

Sandbox.interpreter

@property
def interpreter() -> InterpreterService

Sandbox.pty

@property
def pty() -> PtyService

Sandbox.computer_use

@property
def computer_use() -> ComputerUseService

Sandbox.docker

@property
def docker() -> DockerService

Docker Engine status inside the sandbox; see DockerService.

Sandbox.ports

@property
def ports() -> PortsService

Sandbox.lsp

@property
def lsp() -> LspService

Sandbox.volumes

@property
def volumes() -> SandboxVolumesService

Sandbox.metrics

async def metrics() -> SystemMetrics

Sandbox.exec

async def exec(command: Optional[str] = None,
               *,
               argv: Optional[Sequence[str]] = None,
               session_id: Optional[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. With session_id the command runs in that session's shell instead, where argv and execution_timeout do not apply.

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.types.ProcessResult with stdout, stderr, output, exit_code, and reason.

Sandbox.run_code

async 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.to_json

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

Sandbox.set_labels

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

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

Sandbox.entrypoint_logs

async def entrypoint_logs() -> str

Return the sandbox entrypoint-session log as text.

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

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

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

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

Sandbox.start

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

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

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

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

Sandbox.stop

async def stop() -> None

Warm-stop a persistent sandbox.

Sandbox.fork

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

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.

Sandbox.delete

async def delete() -> None

Delete the sandbox.

Sandbox.set_lifecycle

async def set_lifecycle(*,
                        timeout_secs: Optional[int] = None,
                        on_timeout: Optional[LifecycleAction] = None,
                        idle_timeout_secs: Optional[int] = None,
                        on_idle_timeout: Optional[LifecycleAction] = None,
                        wake_on_request: Optional[bool] = None) -> SandboxLifecycle

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

timeout_secs re-anchors the deadline from now (>= 1; the timeout cannot be disabled). idle_timeout_secs=DISABLED clears the idle pair; arming it on a sandbox with no idle policy requires on_idle_timeout.

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.

Sandbox.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_timeout_secs. 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 set_lifecycle returns. Advance-only: a newer concurrent activity bump keeps the clock, and what comes back is the state that won.

Sandbox.get_network_policy

async def get_network_policy() -> NetworkPolicyInfo

Sandbox.update_network_policy

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

Sandbox.reset_network_policy

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

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

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.

Sandbox.create_snapshot

async def create_snapshot(name: str) -> Snapshot

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

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

Sandbox.create_access_token

async def create_access_token(*,
                              operations: Optional[Sequence[str]] = None,
                              ports: Optional[Sequence[int]] = None,
                              ttl_secs: 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_secs 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.

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

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[int] = field(default=None, kw_only=True)
memory_max Optional[int] = field(default=None, kw_only=True)
disk Optional[int] = field(default=None, kw_only=True)
disk_max Optional[int] = field(default=None, kw_only=True)
vm_class Optional[VmClass] = field(default=None, kw_only=True)
os_family Optional[str] = field(default=None, kw_only=True)
windows_image Optional[str] = field(default=None, kw_only=True)
persistent 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 Optional[SandboxLifecycle] = field(default=None, kw_only=True)
forked_from 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_secs 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_timeout_secs — 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 Sandbox.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.

Attributes:

timeout_secs Optional[int] = None
on_timeout Optional[str] = None
timeout_at Optional[str] = None
idle_timeout_secs 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

PreviewEndpoint

@dataclass(frozen=True)
class PreviewEndpoint()

A sandbox HTTP preview endpoint.

Attributes:

id str
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.ports.PortsService.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.ports.PortsService.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.sandbox.Sandbox.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); timestamps are inclusive bounds.

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
persistent Optional[bool] = None
spot Optional[bool] = None
forked_from Optional[str] = None
min_vcpus Optional[int] = None
max_vcpus Optional[int] = None
min_mem_mib Optional[int] = None
max_mem_mib Optional[int] = None
min_scratch_mib Optional[int] = None
max_scratch_mib Optional[int] = None
created_after Optional[SearchTimestamp] = None
created_before Optional[SearchTimestamp] = None
updated_after Optional[SearchTimestamp] = None
updated_before Optional[SearchTimestamp] = None
last_active_after Optional[SearchTimestamp] = None
last_active_before Optional[SearchTimestamp] = None
sort Optional[SearchSort] = None
order Optional[SearchOrder] = None

SyncSandbox

class SyncSandbox()

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

SyncSandbox.init

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

SyncSandbox.id

@property
def id() -> str

SyncSandbox.name

@property
def name() -> str | None

SyncSandbox.state

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

SyncSandbox.image_build_id

@property
def image_build_id() -> str | None

SyncSandbox.image

@property
def image() -> ImageRef | None

SyncSandbox.snapshot

@property
def snapshot() -> SnapshotRef | None

SyncSandbox.target

@property
def target() -> str | None

SyncSandbox.region

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

SyncSandbox.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]]]

SyncSandbox.labels

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

SyncSandbox.cpu

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

SyncSandbox.cpu_max

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

SyncSandbox.memory

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

SyncSandbox.memory_max

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

SyncSandbox.disk

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

SyncSandbox.disk_max

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

SyncSandbox.os_family

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

SyncSandbox.vm_class

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

SyncSandbox.persistent

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

SyncSandbox.spot

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

SyncSandbox.spot_evicted_at

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

SyncSandbox.lifecycle

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

SyncSandbox.forked_from

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

SyncSandbox.user

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

SyncSandbox.error

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

SyncSandbox.error_reason

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

SyncSandbox.access_token

@property
def access_token() -> str | None

SyncSandbox.access_token_expires_at

@property
def access_token_expires_at() -> str | None

SyncSandbox.toolbox_proxy_url

@property
def toolbox_proxy_url() -> str | None

SyncSandbox.build_logs

def build_logs() -> str

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

SyncSandbox.create_access_token

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

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

SyncSandbox.create_snapshot

def create_snapshot(name: str) -> Snapshot

SyncSandbox.delete

def delete() -> None

Delete the sandbox.

SyncSandbox.entrypoint_logs

def entrypoint_logs() -> str

Return the sandbox entrypoint-session log as text.

SyncSandbox.exec

def exec(command: Optional[str] = None,
         *,
         argv: Optional[Sequence[str]] = None,
         session_id: Optional[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.

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

SyncSandbox.fork

def fork(*, name: Optional[str] = None, memory: Optional[bool] = None) -> SyncSandbox

Fork this sandbox.

SyncSandbox.get_network_policy

def get_network_policy() -> NetworkPolicyInfo

SyncSandbox.metrics

def metrics() -> SystemMetrics

SyncSandbox.pause

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

Pause a persistent linux or macOS sandbox with its memory.

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

SyncSandbox.reset_idle_timer

def reset_idle_timer() -> SandboxLifecycle

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

SyncSandbox.reset_network_policy

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

SyncSandbox.resume

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

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

SyncSandbox.rotate_signing_key

def rotate_signing_key() -> None

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

SyncSandbox.run_code

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

SyncSandbox.set_labels

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

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

SyncSandbox.set_lifecycle

def set_lifecycle(*,
                  timeout_secs: Optional[int] = None,
                  on_timeout: Optional[LifecycleAction] = None,
                  idle_timeout_secs: Optional[int] = None,
                  on_idle_timeout: Optional[LifecycleAction] = None,
                  wake_on_request: Optional[bool] = None) -> SandboxLifecycle

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

SyncSandbox.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).

SyncSandbox.start

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

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

SyncSandbox.stop

def stop() -> None

Warm-stop a persistent sandbox.

SyncSandbox.to_json

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

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

SyncSandbox.update_network_policy

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

SyncSandbox.wait

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

Wait for one public sandbox state and return self.

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

SyncSandbox.computer_use

@property
def computer_use() -> SyncComputerUseService

SyncSandbox.docker

@property
def docker() -> SyncDockerService

Docker Engine status inside the sandbox; see SyncDockerService.

SyncSandbox.fs

@property
def fs() -> SyncFileSystemService

SyncSandbox.git

@property
def git() -> SyncGitService

SyncSandbox.interpreter

@property
def interpreter() -> SyncInterpreterService

SyncSandbox.lsp

@property
def lsp() -> SyncLspService

SyncSandbox.mac_boot_mode

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

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

SyncSandbox.ports

@property
def ports() -> SyncPortsService

SyncSandbox.process

@property
def process() -> SyncProcessService

SyncSandbox.pty

@property
def pty() -> SyncPtyService

SyncSandbox.raw_state

@property
def raw_state() -> str

Wire status string exactly as the server sent it.

SyncSandbox.volumes

@property
def volumes() -> SyncSandboxVolumesService

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