Sandbox

Properties:

• id string
• toolboxProxyUrl? string
• name? string
• image ImageRef | null
• snapshot SnapshotRef | null
• target? string
• labels Record<string, string>
• cpu? number - Reserved CPU (the guarantee), in cores (1 core = 2 vCPUs; a macOS core is one Mac CPU).
• cpuMax? number - CPU limit (the boot shape), in cores; undefined when the API did not report it.
• memory? number
• memoryMax? number
• disk? number
• diskMax? number
• state? SandboxState
• rawState? string
• error? string
• errorReason? string
• imageBuildId? string
• sandboxClass? SandboxClass - 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 - macOS only: whether the sandbox preserves its disk when stopped; undefined on a handle whose metadata has not been loaded yet.
• spot? boolean
• spotEvictedAt? string
• lifecyclePolicy? SandboxLifecycle
• forkedFrom? string
• reservationId? string - macOS only: the ID of the reservation selected for this sandbox. Unset before a reservation is selected, and on search results (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 opaque dtnv_ create token (no known expiry) and for handles without a token.

Constructors

Constructor

new Sandbox(
   sandboxOrId: SandboxDto | 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 sandboxOrId (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:

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

Returns:

• Sandbox

Methods

[Symbol.asyncDispose]()

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

Dispose by deleting the sandbox when constructed with autoDelete.

Returns:

• Promise<void>

buildLogs()

buildLogs(): Promise<string>;

Return retained build output as one-shot text, not a live follower. The body includes the current build state and available output. A sandbox with no image build (for example a registry image) throws NotFoundError. Output can be incomplete while the build is in progress; truncation is indicated in the 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 sandbox services (toolbox, SSH, desktop, private previews) and the self-service API 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>;

Request deletion. Returning, a destroyed state, or a subsequent 404 does not guarantee that the image can already be deleted. Image deletion may still return 409.

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 &), execution 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 copies only the disk, 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 may wait for capacity, as a create does; insufficient capacity can return 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>

getSecrets()

getSecrets(): Promise<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 ifMatch value for replaceSecrets; status is pending until the sandbox has applied desiredRevision.

Returns:

• Promise<SandboxSecretsInfo>

git

get git(): GitService;

Returns:

• GitService

interpreter

get interpreter(): InterpreterService;

Returns:

• InterpreterService

lsp

get lsp(): LspService;

Returns:

• LspService

macBootMode

get macBootMode(): MacBootMode | null;

macOS only: how the sandbox resumed, as reported by the API. 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 macOS sandbox with its memory. 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 API.

Returns:

• Promise<void>

replaceSecrets()

replaceSecrets(
   secrets: readonly string[],
   options: { ifMatch: string }): Promise<SandboxSecretsInfo>;

Replace the full set of project secrets attached to this sandbox (PUT /sandboxes/{id}/secrets). secrets names project secrets. ifMatch is the etag of the last read; a stale one throws PreconditionFailedError. The change applies asynchronously: poll getSecrets until status is applied. Running processes keep their environment; processes started afterwards see the new names.

Parameters:

• secrets readonly string[]
• options { ifMatch: string }

Returns:

• Promise<SandboxSecretsInfo>

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

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)); 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<Image>

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>;

Stop a persistent macOS 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 API or an explicit caller option, never from stored data.

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 current 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>

volumes

get volumes(): SandboxVolumesService;

Returns:

• SandboxVolumesService

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'>

SandboxClass

type SandboxClass = 'linux' | 'macos'

SandboxLifecycle

Lifecycle policy as the API reports it.

timeoutSeconds is the re-arm budget in seconds; 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.

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.
• lastActivityAt? string
• lastActivitySource? string

SandboxLifecycleDto

Wire shape of the lifecycle object on sandbox 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
• last_activity_at? string | null
• last_activity_source? string | 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 — pass options.toolboxUrl to set a toolbox URL explicitly.
• name? string
• image? ImageRef
• snapshot? SnapshotRef
• target? string
• cpu? number
• cpuMax? number
• memory? number
• memoryMax? number
• disk? number
• diskMax? number
• state? SandboxState
• error? string
• imageBuildId? string
• sandboxClass? SandboxClass
• labels? Record<string, string>
• region? string
• persistent? boolean - macOS only: preserve the sandbox's disk when stopped.
• 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, sandboxClass 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, ...).
• sandboxClass? SandboxClass | readonly SandboxClass[] - 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.
• minCores? number - Inclusive bounds on cores_max (the CPU limit), in cores (1 core = 2 vCPUs).
• maxCores? 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.

SandboxSecretsInfo

Properties:

• secrets string[]
• desiredRevision number
• etag string
• httpStatus number
• appliedRevision? number
• status? string
• error? string
• captureStatus? string
• captureUnresolvedCount? number

SandboxStateSnapshot

type SandboxStateSnapshot = api.Snapshot

SandboxDto

Properties:

• id string
• class? SandboxClass | string - Sandbox class (linux | macos); the authoritative class when present.
• name? string
• image? api.ImageReference | null
• status? string
• cpu? number - Reserved CPU (the guarantee), in cores (1 core = 2 vCPUs).
• cores_max? number | null - CPU limit (the boot shape), in cores, a multiple of 0.5.
• memory_mib? number
• memory_max_mib? number | null
• disk_mib? number
• disk_max_mib? number | null
• error? string | null
• labels? unknown
• spot? boolean | null
• spot_evicted_at? string | null
• toolboxProxyUrl? string
• toolbox_proxy_url? string | null
• region_id? string
• image_build_id? string | null
• user? string | null
• snapshot? api.SnapshotReference | null
• mac_boot_mode? string | null - macOS only: set on the running that ends a resume; null otherwise.
• reservation_id? string | null - macOS only: the reservation selected for this sandbox. GET /sandboxes/search items omit it.
• persistent? boolean | null - macOS only; absent on GET /sandboxes/batch-wait items.
• lifecycle_policy? SandboxLifecycleDto | null
• created_at? string | null - Present on GET /sandboxes/search items; absent on the plain list. created_at is always set on a search item; the other timestamps and forked_from are null when the sandbox has no such event.
• updated_at? string | null
• last_activity_at? string | null
• started_at? string | null
• stopped_at? string | null
• forked_from? string | null
• cursor? string - Per-item cursor on search results.

PreviewEndpoint

Properties:

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

PreviewLink

Preview URL plus an access token for one sandbox port.

Send token in the X-Daytona-Preview-Token header to reach a private endpoint; without a credential the request returns 401. When token is a sandbox access token (a JWT) it also works as Authorization: Bearer or ?daytona_token=; an opaque preview 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 has no readable expiry.

SignedPreviewLink

Self-contained signed URL for one sandbox 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 sandbox services (toolbox, SSH, desktop, private previews) and for the self-service API 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 = string

How a macOS sandbox resumed, as reported by the API.