Sandbox

Sandbox is the handle for one sandbox (a Firecracker microVM). You never construct it directly — obtain one from daytona.create(), daytona.get(), or daytona.list(). Field and method names mirror the official Daytona SDK; data is hydrated from the control plane, and file/git/process calls go through the toolbox proxy.

Properties

Property	Type	Description
`id`	`str`	Sandbox id.
`name`	`str`	Sandbox name.
`snapshot`	`str`	The image ref the sandbox was created from.
`mode`	`str`	Scheduling mode: `burstable` or `dedicated`.
`cpu`	`float`	vCPUs.
`gpu`	`int`	Always `0` currently.
`memory`	`int`	Memory in GiB (rounded up from MiB).
`disk`	`int`	Scratch disk in GiB (rounded up from MiB).
`state`	`str`	`creating`, `starting`, `started`, `stopping`, `stopped`, `destroying`, `destroyed`, `error`, or `unknown`.
`error_reason`	`str`	Failure reason when `state == "error"`.
`runner_id`	`str`	Id of the runner hosting the sandbox.
`target`	`str`	The client's target label.
`access_token`	`str`	Per-sandbox toolbox credential; populated only on the handle returned by `create()`.
`toolbox_proxy_url`	`str`	Toolbox base URL for this sandbox: `{toolbox_url}/{id}`.

Toolbox accessors

sandbox.process — Process: commands, code runs, sessions
sandbox.fs — FileSystem: file operations
sandbox.git — Git: git operations

refresh_data()

Re-fetches the sandbox row from the API and updates the handle's properties in place.

Python

def refresh_data() -> None

start()

Starts the sandbox and waits for started. A persistent sandbox (created with persistent=True) can be warm-started from stopped: its write layer survives, so it re-boots on any capable runner (with a fresh network identity). A non-persistent sandbox has no warm start — recreate it instead.

Python

def start(timeout: int = 60) -> None

Raises: DaytonaValidationError for a negative timeout; DaytonaNotSupportedError if the sandbox is not persistent, or its state is destroyed/error; DaytonaTimeoutError if it does not start in time. See stop & start.

stop()

Warm-stops a persistent sandbox: kills the VM but keeps its write layer, so a later start() resumes from the same disk. Processes do not survive a stop.

Python

def stop() -> None

Raises: DaytonaNotSupportedError if the sandbox is not persistent (delete instead).

pause()

Memory-preserving pause of a persistent sandbox: captures guest RAM and processes to durable storage and tears the VM down. A later resume() restores it so processes continue exactly where they left off. Refused for non-persistent sandboxes and for sandboxes with volumes or a docker device.

Python

def pause() -> None

Raises: DaytonaNotSupportedError when the sandbox is not eligible. See pause & resume.

resume()

Resumes a paused persistent sandbox from its memory snapshot, restoring guest RAM. Unlike start() (which cold-boots and loses processes), resume continues running processes.

Python

def resume(timeout: int = 60) -> None

Raises: DaytonaValidationError for a negative timeout; DaytonaNotSupportedError unless the sandbox is a paused persistent sandbox; DaytonaTimeoutError if it does not come up in time.

fork()

Duplicates a persistent sandbox — guest RAM and filesystem, at the current instant — into a new, independent sandbox. A running source is forked live (brief internal freeze; the source keeps running); a paused source forks with no freeze. The fork lands paused: call resume() on the returned handle to continue its processes, or start() to cold-boot its filesystem.

Python

def fork(name: str | None = None) -> Sandbox

Returns: the new Sandbox (paused). Raises: DaytonaNotSupportedError for non-persistent sandboxes or ones with volumes/docker. See the fork guide.

Python

child = sandbox.fork(name="experiment-1")
child.resume()  # processes continue from the fork instant

get_preview_link()

Returns a Daytona-compatible preview link for an in-sandbox HTTP port. On first call the port is registered as private, so requests need the returned token (send it in the x-daytona-preview-token header). Repeated calls are idempotent and return the same URL and token.

Python

def get_preview_link(port: int) -> PreviewLink

Returns: PreviewLink(url, token, legacy_proxy_url). Raises: DaytonaError if port is not an integer in 1–65535.

Python

preview = sandbox.get_preview_link(3000)
requests.get(preview.url, headers={"x-daytona-preview-token": preview.token})

expose_port()

Exposes an in-sandbox HTTP port on a stable URL. Defaults to private (fail-closed); pass public=True only for content safe to serve to anyone with the URL. Declarative and idempotent: if the port is already exposed this returns the existing endpoint, adjusting its visibility if it differs.

Python

def expose_port(port: int, public: bool = False) -> PreviewEndpoint

Parameter	Type	Default	Description
`port`	`int`	—	In-sandbox port, 1–65535.
`public`	`bool`	`False`	Serve without authentication.

Returns: PreviewEndpoint(id, port, public, url, created_at). See port forwarding.

list_preview_endpoints()

Lists the sandbox's registered preview endpoints.

Python

def list_preview_endpoints() -> List[PreviewEndpoint]

set_preview_public()

Flips an exposed port between public and private. Takes effect within about a second — the control plane notifies the proxies rather than waiting for a cache TTL.

Python

def set_preview_public(port: int, public: bool) -> PreviewEndpoint

Raises: DaytonaError (404) if the port is not exposed.

unexpose_port()

Stops exposing a port. Idempotent — unexposing an unexposed port is a no-op.

Python

def unexpose_port(port: int) -> None

create_snapshot()

Captures a native VM-state snapshot of a running sandbox — a real disk (or memory+disk) capture, not a Daytona image alias (those are managed by SnapshotService).

Python

def create_snapshot(name: str, kind: str = "disk") -> Dict[str, str]

Parameter	Type	Default	Description
`name`	`str`	—	Snapshot name.
`kind`	`str`	`"disk"`	`"disk"` or `"full"` (memory+disk).

Returns: {"snapshot_id": ..., "job_id": ...}. See VM snapshots.

delete()

Deletes the sandbox. After deletion the handle's state becomes destroyed.

Python

def delete() -> None

wait_until_started()

Polls the sandbox until it reaches started. Used internally by create()/start()/resume(); call it directly if you observed a transitional state.

Python

def wait_until_started(timeout: int = 60) -> None

Raises: DaytonaError if the sandbox lands in error; DaytonaTimeoutError on timeout (timeout=0 waits indefinitely); DaytonaValidationError for a negative timeout.

archive()

Not supported on Daytona — always raises DaytonaNotSupportedError. Present for Daytona API compatibility.

Python

def archive() -> None

On this page