Daytona v2

Documentation for Daytona v2, currently in alpha. For the latest release, see Daytona v0.

Sandbox

Properties:

• id string
• toolboxProxyUrl? string
• capabilities SandboxCapabilities
• name? string
• image ImageRef | null
• snapshot SnapshotRef | null
• target? string
• labels Record<string, string>
• cpu? number
• cpuMax? number
• memory? number
• memoryMax? number
• disk? number
• diskMax? number
• state? SandboxState
• rawState? string
• error? string
• errorReason? string
• imageBuildId? string
• vmClass? VmClass - Undefined until fetched, and for a class this SDK does not know (calls that depend on the class then throw).
• user? string
• region? string
• persistent? boolean - Whether the sandbox has a persistent write layer; undefined on a handle whose metadata has not been loaded yet.
• archived? boolean - Whether the sandbox is archived: its disk was moved to object storage, and the next start() restores it first. state stays stopped. Undefined when not known (a rehydrated handle that has not been refreshed, a batch-wait read, or a search item).
• spot? boolean
• spotEvictedAt? string
• lifecyclePolicy? SandboxLifecycle
• forkedFrom? string
• reservationId? string - macOS only: the external ID of the reservation selected by the current or latest successful claim. Unset before first claim, and on search-index reads (search(), a search-routed list()), which omit it; refreshData() reads it.
• accessToken? string
• accessTokenExpiresAt? string - Expiry of accessToken (RFC 3339), when known. Undefined for the compat-window opaque dtnv_ create token (no known expiry) and for handles without a token.

Constructors

Constructor

new Sandbox(
   vmOrId: VmDto | SandboxInfo | string,
   api: AxiosInstance | undefined,
   toolboxBaseUrl: string | undefined,
   apiKey: string | undefined,
   target?: string,
   options?: SandboxConnectOptions,
   requestTimeout?: number,
   httpOptions?: HttpClientOptions): Sandbox;

Low-level constructor; prefer daytona.create*(), get(id) or list(). Any toolbox URL inside vmOrId (a stored toJSON() blob or an API-shaped object) is ignored, so stored data never chooses where the SDK sends a credential. Pass options.toolboxUrl to set one explicitly — the toolbox credential (the API key, a project token, a minted sandbox token, or options.accessToken) goes there, so pass only a URL you trust. The third parameter, toolboxBaseUrl, is unused: pass the URL as options.toolboxUrl.

Parameters:

• vmOrId VmDto | SandboxInfo | string
• api AxiosInstance | undefined
• toolboxBaseUrl string | undefined
• apiKey string | undefined
• target? string
• options? SandboxConnectOptions
• requestTimeout? number
• httpOptions? HttpClientOptions

Returns:

• Sandbox

Constructor

new Sandbox(
   vmOrId: VmDto | SandboxInfo | string,
   api: AxiosInstance | undefined,
   toolboxBaseUrl: string | undefined,
   apiKey: string | undefined,
   target: string | undefined,
   options: SandboxConnectOptions | undefined,
   requestTimeout: number | undefined,
   httpOptions: HttpClientOptions | undefined,
   hub: WaitHub | undefined): Sandbox;

Parameters:

• vmOrId VmDto | SandboxInfo | string
• api AxiosInstance | undefined
• toolboxBaseUrl string | undefined
• apiKey string | undefined
• target string | undefined
• options SandboxConnectOptions | undefined
• requestTimeout number | undefined
• httpOptions HttpClientOptions | undefined
• hub WaitHub | undefined

Returns:

• Sandbox

Constructor

new Sandbox(
   vmOrId: VmDto | SandboxInfo | string,
   api: AxiosInstance | undefined,
   toolboxBaseUrl: string | undefined,
   apiKey: string | undefined,
   target?: string,
   options: SandboxConnectOptions = {},
   requestTimeout?: number,
   httpOptions?: HttpClientOptions,
   hub?: WaitHub): Sandbox;

Parameters:

• vmOrId VmDto | SandboxInfo | string
• api AxiosInstance | undefined
• toolboxBaseUrl string | undefined
• apiKey string | undefined
• target? string
• options SandboxConnectOptions = {}
• requestTimeout? number
• httpOptions? HttpClientOptions
• hub? WaitHub

Returns:

• Sandbox

Methods

[Symbol.asyncDispose]()

[Symbol.asyncDispose](): Promise<void>;

Dispose by deleting the sandbox when constructed with autoDelete (never a persistent restore).

Returns:

• Promise<void>

archive()

archive(): Promise<void>;

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.

Returns:

• Promise<void>

attachHub()

attachHub(hub: WaitHub): void;

Parameters:

• hub WaitHub

Returns:

• void

buildLogs()

buildLogs(): Promise<string>;

Return retained build output as one-shot text, not a live follower. The body includes a state line and 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) throws NotFoundError. Before a capture is assigned, the response can contain only build state. An expired or unreachable capture can throw BUILD_LOG_UNAVAILABLE; retained-tail truncation is indicated in the text. Discovery chooses the owning service explicitly and returns its current retained output as text. Use followBuildLogs for live output and completeness metadata.

Returns:

• Promise<string>

computerUse

get computerUse(): ComputerUseService;

Returns:

• ComputerUseService

createAccessToken()

createAccessToken(options: CreateAccessTokenOptions = {}): Promise<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. It expires at expiresAt, cannot be refreshed, and can never mint further credentials; mint a fresh one here instead. An unknown operation or an over-cap ttlSeconds is a 400, never a silent narrowing.

Parameters:

• options CreateAccessTokenOptions = {}

Returns:

• Promise<SandboxAccessToken>

createSnapshot()

createSnapshot(name: string): Promise<Snapshot>;

Parameters:

• name string

Returns:

• Promise<Snapshot>

delete()

delete(): Promise<void>;

Returns:

• Promise<void>

docker

get docker(): DockerService;

Docker Engine status inside the sandbox; see DockerService.

Returns:

• DockerService

entrypointLogs()

entrypointLogs(): Promise<string>;

Return the sandbox entrypoint log as plain text.

Returns:

• Promise<string>

exec()

exec(command: ProcessCommand, options: RunOptions = {}): Promise<RunResult>;

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

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

Shell selection. Passing a string runs the command 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. Pass { argv: [...] } to bypass the shell entirely, which is the safe form for untrusted arguments. Use process.createSession() when commands need shared shell state.

Background processes. The call returns when the shell exits. If the command launches a background child that holds its output descriptors 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 ProcessService.start, which returns a ProcessHandle immediately (logs, wait, kill). Alternatively redirect: nohup cmd > server.log 2>&1 &.

Parameters:

• command ProcessCommand - Shell command string, or { argv } for shell-free execution.
• options RunOptions = {}

Returns:

• Promise<RunResult>

followBuildLogs()

followBuildLogs(options: BuildLogFollowOptions): Promise<BuildLogFollowResult>;

Observe this sandbox’s build without changing its execution lifetime. Discovery failures, including a 404 for a sandbox with no image build, throw BuildLogInterruptedError with the HTTP status and last cursor. They do not fall back to another log source.

Parameters:

• options BuildLogFollowOptions

Returns:

• Promise<BuildLogFollowResult>

fork()

fork(
   options: { name?: string; memory?: boolean; timeout?: number } = {}): Promise<Sandbox>;

Fork this sandbox and return the fork handle.

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.

Parameters:

• options { name?: string; memory?: boolean; timeout?: number } = {}

Returns:

• Promise<Sandbox>

fs

get fs(): FileSystemService;

Returns:

• FileSystemService

getNetworkPolicy()

getNetworkPolicy(): Promise<NetworkPolicyInfo>;

Returns:

• Promise<NetworkPolicyInfo>

git

get git(): GitService;

Returns:

• GitService

interpreter

get interpreter(): InterpreterService;

Returns:

• InterpreterService

learnCell()

learnCell(cell: string | undefined): void;

Parameters:

• cell string | undefined

Returns:

• void

lsp

get lsp(): LspService;

Returns:

• LspService

macBootMode

get macBootMode(): MacBootMode | null;

macOS only: how the sandbox came back from its last resume, set on the started that ends it. With cold_after_restore_failure the memory could not be restored, the Mac booted the disk, and errorReason says why. Null for any other class and for a sandbox not resumed since it last booted.

Returns:

• MacBootMode | null

metrics()

metrics(): Promise<SystemMetrics>;

Returns:

• Promise<SystemMetrics>

pause()

pause(options: LifecycleWaitOptions = {}): Promise<void>;

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 throws SandboxTerminalStateError if the pause fails. A paused macOS sandbox keeps its Mac slot but does not keep its reservation renewing.

Parameters:

• options LifecycleWaitOptions = {}

Returns:

• Promise<void>

ports

get ports(): PortsService;

Returns:

• PortsService

process

get process(): ProcessService;

Returns:

• ProcessService

pty

get pty(): PtyService;

Returns:

• PtyService

refreshData()

refreshData(): Promise<void>;

Refresh sandbox metadata from the control plane.

Returns:

• Promise<void>

resetIdleTimer()

resetIdleTimer(): Promise<SandboxLifecycle>;

Reset this sandbox’s idle timer: an explicit keepalive for work the platform cannot see.

Bumps the sandbox’s activity clock (lastActivityAt, attributed server-side to the api source), which restarts the idle countdown — idleTimeoutAt re-anchors to now + idleExpirySeconds. The wall-clock timeoutAt is NOT affected. Succeeds whether or not an idle timeout is armed (an unarmed sandbox echoes idleTimeoutAt: undefined), 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 updateLifecyclePolicy() returns. Advance-only: a newer concurrent activity bump keeps the clock, and what comes back is the state that won.

Returns:

• Promise<SandboxLifecycle>

resetNetworkPolicy()

resetNetworkPolicy(options: { ifMatch: string }): Promise<NetworkPolicyInfo>;

Parameters:

• options { ifMatch: string }

Returns:

• Promise<NetworkPolicyInfo>

resume()

resume(options: LifecycleWaitOptions = {}): Promise<void>;

Resume a paused linux or macOS sandbox and wait until it is started. A macOS resume the Mac cannot finish ends stopped; this then throws SandboxTerminalStateError.

Parameters:

• options LifecycleWaitOptions = {}

Returns:

• Promise<void>

rotateSigningKey()

rotateSigningKey(): Promise<void>;

Rotate the sandbox’s signing key: every pre-signed URL minted so far stops working within ~30 s; new URLs from presignedDownloadUrl/UploadUrl 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 reject before any request.

Returns:

• Promise<void>

runCode()

runCode(code: string, options: InterpreterRunOptions = {}): Promise<InterpreterResult>;

Parameters:

• code string
• options InterpreterRunOptions = {}

Returns:

• Promise<InterpreterResult>

setLabels()

setLabels(labels: Record<string, string>): Promise<Record<string, string>>;

Replace the sandbox’s full label set. Pass {} to clear all labels; resolves to the applied labels.

Parameters:

• labels Record<string, string>

Returns:

• Promise<Record<string, string>>

snapshotFilesystem()

snapshotFilesystem(options: CaptureImageOptions = {}): Promise<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(); a Linux sandbox keeps running. A macOS sandbox must be persistent and stopped; it cannot start until the snapshot is ready.

Parameters:

• options CaptureImageOptions = {}

Returns:

• Promise<img />

start()

start(options: LifecycleWaitOptions = {}): Promise<void>;

Start a stopped sandbox, or resume a paused one, and wait until it is started.

Parameters:

• options LifecycleWaitOptions = {}

Returns:

• Promise<void>

stop()

stop(): Promise<void>;

Warm-stop a persistent sandbox.

Returns:

• Promise<void>

toJSON()

toJSON(): SandboxHandleJSON;

The sandbox’s data as JSON. A snapshot, not a way back: resume a stored sandbox with daytona.get(info.sandboxId). It carries no toolbox URL — where a credential goes always comes from the control plane or an explicit caller option, never from stored data (#3398).

Returns:

• SandboxHandleJSON

updateEnv()

updateEnv(
   env: Record<string, string> = {},
   options: UpdateEnvOptions = {}): Promise<void>;

Update the extra environment layer used by processes created after this call.

Parameters:

• env Record<string, string> = {}
• options UpdateEnvOptions = {}

Returns:

• Promise<void>

updateLifecyclePolicy()

updateLifecyclePolicy(options: LifecyclePolicyOptions): Promise<SandboxLifecycle>;

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

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

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.

Parameters:

• options LifecyclePolicyOptions

Returns:

• Promise<SandboxLifecycle>

updateNetworkPolicy()

updateNetworkPolicy(
   networkPolicy: NetworkPolicyInput,
   options: { ifMatch: string }): Promise<NetworkPolicyInfo>;

Parameters:

• networkPolicy NetworkPolicyInput
• options { ifMatch: string }

Returns:

• Promise<NetworkPolicyInfo>

wait()

wait(options: WaitOptions = {}): Promise<Sandbox>;

Wait for one or more public sandbox states.

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

Parameters:

• options WaitOptions = {}

Returns:

• Promise<Sandbox>

waitForState()

waitForState(
   states: readonly SandboxWaitState[],
   options: WaitForStateOptions = {}): Promise<void>;

Parameters:

• states readonly SandboxWaitState[]
• options WaitForStateOptions = {}

Returns:

• Promise<void>

---

UpdateEnvOptions

Properties:

• unset? readonly string[]

---

SandboxEventsConfig

Configuration for the sandbox-state events hub (WebSocket-based waiting).

enabled defaults to true. reconcileIntervalMs defaults to 60 000 (ms); 0 disables the periodic re-subscribe timer. idleCloseMs closes the events socket that long after its last waiter leaves; unset, the socket stays open. In Node an idle socket does not keep the process alive, so a script that never calls daytona.close() still exits; a runtime where the socket cannot be released that way (no ws package) closes it after 10 000 ms instead. 0 keeps the socket open until close().

Properties:

• enabled? boolean - Enable WebSocket-based waiting; default true.
• reconcileIntervalMs? number - Reconcile timer interval in ms; default 60 000; 0 disables. Values above 2 147 483 647 clamp to that maximum.
• idleCloseMs? number - Close an idle events socket after this many ms; default never (10 000 where an idle socket would keep the process alive); 0 = never. Values above 2 147 483 647 clamp to that maximum.

---

SandboxState

type SandboxState =
  | 'queued'
  | 'creating'
  | 'starting'
  | 'started'
  | 'pausing'
  | 'stopping'
  | 'stopped'
  | 'paused'
  | 'destroying'
  | 'destroyed'
  | 'error'
  | 'unknown'

---

SandboxWaitState

type SandboxWaitState = Exclude<SandboxState, 'creating' | 'error' | 'unknown'>

---

SandboxLifecycle

Lifecycle policy as the control plane reports it.

timeoutSeconds is the stored re-arm budget in seconds (echoed, unlike the old write-only TTL anchor); timeoutAt is the current absolute deadline it derives. timeoutAt, idleTimeoutAt, lastActivityAt and lastActivitySource are server-derived and read-only. An action the SDK does not know yet (a newer server) is passed through as its wire string. archiveIntervalSeconds is undefined for a sandbox that is never archived (not linux persistent).

Properties:

• timeoutSeconds? number
• onTimeout? string
• timeoutAt? string
• idleExpirySeconds? number
• onIdleTimeout? string
• idleTimeoutAt? string - When onIdleTimeout becomes eligible to fire: lastActivityAt + idleExpirySeconds, server-derived and read-only. Undefined when the idle pair is not armed or the sandbox has never been active. Any activity — traffic, SSH, a non-PTY process or code execution started through the process API that is still running (exec, process.start, runCode and interpreter cells included), or sandbox.resetIdleTimer() — advances lastActivityAt and pushes it.
• wakeOnRequest boolean
• lastActivityAt? string
• lastActivitySource? string
• archiveIntervalSeconds? number

---

SandboxLifecycleDto

Wire shape of the lifecycle object on VM DTOs and the lifecycle PATCH response.

Properties:

• timeout_seconds? number | null
• on_timeout? string | null
• timeout_at? string | null
• idle_expiry_seconds? number | null
• on_idle_timeout? string | null
• idle_timeout_at? string | null
• wake_on_request? boolean | null
• last_activity_at? string | null
• last_activity_source? string | null
• archive_interval_seconds? number | null

---

SandboxInfo

Properties:

• sandboxId string
• toolboxProxyUrl? string - Internal: the create path passes the create response’s toolbox URL here. toJSON() never writes it, and the public Sandbox constructor ignores it (#3398) — pass options.toolboxUrl to set a toolbox URL explicitly.
• capabilities? SandboxCapabilities
• name? string
• image? ImageRef
• snapshot? SnapshotRef
• target? string
• cpu? number
• cpuMax? number
• gpu? number
• memory? number
• memoryMax? number
• disk? number
• diskMax? number
• state? SandboxState
• error? string
• imageBuildId? string
• vmClass? VmClass
• labels? Record<string, string>
• region? string
• persistent? boolean
• archived? boolean
• spot? boolean
• spotEvictedAt? string
• lifecyclePolicy? SandboxLifecycle
• forkedFrom? string
• reservationId? string
• user? string

---

SandboxHandleJSON

type SandboxHandleJSON = SandboxInfo

---

WaitOptions

Properties:

• until? SandboxWaitState | readonly SandboxWaitState[]
• timeout? number

---

WaitForStateOptions

Properties:

• terminalStates? readonly SandboxState[]
• timeout? number - Caller wait budget in milliseconds; 0 and undefined wait unbounded.

---

SandboxSearchFilters

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

status, vmClass 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); numeric bounds and timestamp starts are inclusive; timestamp ends are exclusive.

Properties:

• q? string - Free text over name and image; also an exact match when it is a sandbox id.
• status? string | readonly string[] - A single value or a list (any-of) over the API’s lifecycle state names (running, stopped, …).
• vmClass? VmClass | readonly VmClass[] - A single value or a list (any-of).
• region? string | readonly string[] - A single value or a list (any-of) over region slugs.
• imageRef? string
• imageRefPrefix? string
• labels? Record<string, string> - Containment: every listed label must match.
• spot? boolean
• forkedFrom? string - Sandboxes forked from this sandbox id.
• minVcpus? number
• maxVcpus? number
• minMemoryMib? number
• maxMemoryMib? number
• minDiskMib? number
• maxDiskMib? number
• createdStartAt? SearchTimestamp
• createdEndAt? SearchTimestamp
• updatedStartAt? SearchTimestamp
• updatedEndAt? SearchTimestamp
• lastActivityStartAt? SearchTimestamp
• lastActivityEndAt? SearchTimestamp
• sort? SearchSort - Defaults to created_at.
• order? SearchOrder - Defaults to desc.

---

SandboxCapabilities

Properties:

• process? boolean
• fs? boolean
• git? boolean
• pty? boolean
• interpreter? boolean
• signals? boolean

---

PreviewEndpoint

Properties:

• port number
• public boolean
• url string
• createdAt? string

---

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.

For a shareable URL that works in a browser without extra headers, use PortsService.signedPreviewLink instead.

Example:

const link = await sandbox.ports.previewLink(8080)
const response = await fetch(link.url, {
  headers: { 'X-Daytona-Preview-Token': link.token },
})

Properties:

• url string
• token string
• expiresAt? string - Absent when the preview token is public/HMAC-backed or its JWT payload was unreadable.

---

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 expiresAt (RFC 3339). Revoke it early with PortsService.expireSignedPreviewLink.

Properties:

• url string
• token string
• expiresAt? string - Absent when the server response carried no expiry (parity with the Python SDK’s expires_at: Optional[str]).

---

CreateAccessTokenOptions

Options for Sandbox.createAccessToken.

Properties:

• operations? readonly string[] - Requested operation subset (the sandbox-operation vocabulary: toolbox, toolbox:exec, toolbox:fs, toolbox:git, toolbox:lsp, desktop, ssh, sandbox:stop, sandbox:pause, sandbox:delete). Omitted = the minter’s full grantable set; [] is a valid ports-only grant. Unknown operations are a 400, never a silent narrowing.
• ports? readonly number[] - Private-preview ports the token may reach. Omitted = all; [] = none.
• ttlSeconds? number - Token lifetime in seconds; omitted = the deployment default, capped server-side.

---

SandboxAccessToken

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

accessToken is a bearer for the sandbox data plane (toolbox, SSH, desktop, private previews) and for the self-service control routes named by operations. It expires at expiresAt (RFC 3339) and cannot be refreshed — mint a fresh one with Sandbox.createAccessToken instead. ports is the granted private-preview port set; undefined means every port.

Properties:

• accessToken string
• tokenType string
• expiresAt string
• operations readonly string[]
• ports? readonly number[]

---

SystemMetrics

Properties:

• timestamp string
• cpuCount number
• cpuUtilization number
• memoryUsageBytes number
• memoryTotalBytes number
• diskUsageBytes number
• diskTotalBytes number

---

MacBootMode

type MacBootMode = 'restored' | 'cold_after_restore_failure' | (string & {})

How a macOS sandbox came back from its last resume: restored from its saved memory, or cold_after_restore_failure when the memory could not be restored and the Mac booted the disk. Open: a newer server’s value comes through as is.