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

Toolbox accessors

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

refreshData()

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

refreshData(): Promise<void>

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.

start(timeout = 60): Promise<void>

Throws: 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.

stop(): Promise<void>

Throws: 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.

pause(): Promise<void>

Throws: 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.

resume(timeout = 60): Promise<void>

Throws: 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.

fork(name?: string): Promise<Sandbox>

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

const child = await sandbox.fork('experiment-1')
await child.resume() // processes continue from the fork instant

getPreviewLink()

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.

getPreviewLink(port: number): Promise<PreviewLink>

Returns: { url, token, legacyProxyUrl? }. Throws: DaytonaError if port is not an integer in 1–65535.

const preview = await sandbox.getPreviewLink(3000)
const res = await fetch(preview.url, {
  headers: { 'x-daytona-preview-token': preview.token },
})

exposePort()

Exposes an in-sandbox HTTP port on a stable URL. Defaults to private (fail-closed); pass isPublic: 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.

exposePort(port: number, isPublic = false): Promise<PreviewEndpoint>

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

listPreviewEndpoints()

Lists the sandbox's registered preview endpoints.

listPreviewEndpoints(): Promise<PreviewEndpoint[]>

setPreviewPublic()

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.

setPreviewPublic(port: number, isPublic: boolean): Promise<PreviewEndpoint>

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

unexposePort()

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

unexposePort(port: number): Promise<void>

createSnapshot()

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

createSnapshot(name: string, kind: 'disk' | 'full' = 'disk'): Promise<{ snapshotId: string; jobId: string }>

Returns: { snapshotId, jobId }. See VM snapshots.

delete()

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

delete(): Promise<void>

waitUntilStarted()

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

waitUntilStarted(timeout = 60): Promise<void>

Throws: 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 throws DaytonaNotSupportedError. Present for Daytona API compatibility.

archive(): Promise<void>