Daytona

Properties:

images ImagesService
snapshots SnapshotsService
volume VolumeService
secret SecretService
reservations ReservationsService

Constructors

Constructor

new Daytona(config: DaytonaConfig = {}): Daytona;

Parameters:

config DaytonaConfig = {}

Returns:

Daytona

Methods

auditScenarios()

auditScenarios(): Promise<api.AuditScenarios>;

Return the actions the audit log can record for each target type.

Returns:

Promise<api.AuditScenarios>

create()

create(image: string, options: CreateSandboxOptions = {}): Promise<Sandbox>;

Parameters:

image string
options CreateSandboxOptions = {}

Returns:

Promise<Sandbox>

createFromBuild()

createFromBuild(
   builder: ImageBuilder,
   options: CreateSandboxOptions & Omit<BuildImageOptions, 'region'> = {}): Promise<Sandbox>;

Build an anonymous image, wait for it, then create the sandbox from it. target selects the region for BOTH legs: a Dockerfile-built image lives in one region and can only boot there (DP-2), so it is built where the sandbox will run. BuildImageOptions.region is therefore not accepted here — pass target.

Parameters:

builder ImageBuilder
options CreateSandboxOptions & Omit<BuildImageOptions, 'region'> = {}

Returns:

Promise<Sandbox>

createFromSnapshot()

createFromSnapshot(
   snapshot: string,
   options: CreateSandboxFromSnapshotOptions = {}): Promise<Sandbox>;

Parameters:

snapshot string
options CreateSandboxFromSnapshotOptions = {}

Returns:

Promise<Sandbox>

createMacos()

createMacos(image: string, options: CreateMacosSandboxOptions = {}): Promise<Sandbox>;

Create a macOS sandbox (POST /sandboxes/macos) on a Mac the organization has reserved (daytona.reservations), from a macOS image name. reservation picks the lease: omitted packs the sandbox onto a reserved Mac with room (or lets the organization's auto-reserve buy one), 'new' buys a lease for it, and a reservation id places it on that lease. With no lease to use it fails with ConflictError (NO_ACTIVE_RESERVATION, NO_FREE_SLOT, AUTO_RESERVE_LIMIT_REACHED, NO_MAC_AVAILABLE). The Mac sets the size (half of it per sandbox), which the sandbox reports from its first boot on. name, idempotencyKey, wait and createTtl behave as on create.

Creating macOS sandboxes requires the organization's macos_sandboxes feature flag; without it the API answers 403 FEATURE_FLAG_DISABLED (thrown as AuthorizationError).

Parameters:

image string
options CreateMacosSandboxOptions = {}

Returns:

Promise<Sandbox>

currentApiKey()

currentApiKey(): Promise<api.CurrentApiKey>;

Describe the API key this client authenticates with: its name, masked display parts, the project and organization it acts in, its permissions, expiry and last use. The token itself is never returned.

Returns:

Promise<api.CurrentApiKey>

delete()

delete(sandbox: Sandbox | string): Promise<void>;

Parameters:

sandbox Sandbox | string

Returns:

Promise<void>

findByName()

findByName(name: string, options: { target?: string } = {}): Promise<Sandbox[]>;

Sandboxes created with { name }, newest first; [] when none.

Exact match on the labels.name every create*({ name }) stamps (issue #1935), read through the region-local GET /sandboxes?labels= filter — synchronous and read-your-writes, so a sandbox created a moment ago is found (unlike the eventually consistent search index behind list filters). Names are not unique, so this is an array: a get-or-create caller takes [0] when it is non-empty and calls create(image, { name }) otherwise — and because that create derives the same key as the first one, a lost race between two such callers still yields one sandbox. Sandboxes that are deleted or deleting are left out (their create key is already released).

target scopes the read the way it scopes a create: it defaults to the client's target, is sent as the same x-daytona-region selector create*() sends, and 'local' means this API host's own region — so the lookup reads the cell the named create landed in, which is the create ledger's scope.

Parameters:

name string
options { target?: string } = {}

Returns:

Promise<Sandbox[]>

get()

get(id: string, options: SandboxConnectOptions = {}): Promise<Sandbox>;

Fetch a sandbox by id.

Parameters:

id string
options SandboxConnectOptions = {}

Returns:

Promise<Sandbox>

getNetworkPolicy()

getNetworkPolicy(sandbox: Sandbox | string): Promise<NetworkPolicyInfo>;

Parameters:

sandbox Sandbox | string

Returns:

Promise<NetworkPolicyInfo>

getProjectBudget()

getProjectBudget(): Promise<ProjectBudget | null>;

Return the monthly spend budget of the API key's project, or null when the project has no budget. The key needs the read:spending permission. Spend is calculated at list price, before credits, and lags usage by several minutes. While the project is over its budget, creating or starting a sandbox in it throws ProjectBudgetExceededError.

Returns:

Promise<ProjectBudget | null>

iter()

iter(options: ListSandboxesOptions = {}): AsyncIterable<Sandbox>;

Parameters:

options ListSandboxesOptions = {}

Returns:

AsyncIterable<Sandbox>

list()

list(options: ListSandboxesOptions = {}): Promise<ListResult<Sandbox>>;

List sandboxes as one page { items, nextCursor }.

With only cursor/limit this is the read-your-writes path: one page of the region-local GET /sandboxes. A sandbox you just created is in the result; walk further pages with iter or the returned cursor.

Any other option — including id/name (sent as idPrefix/namePrefix), q, status, vmClass, region, labels, the resource and timestamp bounds, sort, order — switches the call to a single GET /sandboxes/search request, the same surface as search, and fills total, totalRelation and partialRegions on the result. That path is eventually consistent: a committed change is searchable after roughly 2-3 s, it spans every region rather than only this API host's, and partialRegions names regions whose index is still backfilling and may be incomplete. The cursor it returns is opaque, tied to the exact filter and sort that produced it (reusing it with a different filter or sort is a 400), and paging is best-effort under concurrent mutation: a sandbox whose sort field changes between pages can be seen twice or missed. If the API host has search disabled (501, SearchNotConfiguredError with code === 'SEARCH_NOT_CONFIGURED') or the index is unreachable (503, SearchUnavailableError with code === 'SEARCH_UNAVAILABLE'), drop the search options to fall back to the GET /sandboxes path.

Parameters:

options ListSandboxesOptions = {}

Returns:

Promise<ListResult<Sandbox>>

pause()

pause(
   sandbox: Sandbox | string,
   options: { readonly timeout?: number } = {}): Promise<void>;

Parameters:

sandbox Sandbox | string
options { readonly timeout?: number } = {}

Returns:

Promise<void>

resetNetworkPolicy()

resetNetworkPolicy(
   sandbox: Sandbox | string,
   options: { ifMatch: string }): Promise<NetworkPolicyInfo>;

Parameters:

sandbox Sandbox | string
options { ifMatch: string }

Returns:

Promise<NetworkPolicyInfo>

resume()

resume(
   sandbox: Sandbox | string,
   options: { readonly timeout?: number } = {}): Promise<void>;

Parameters:

sandbox Sandbox | string
options { readonly timeout?: number } = {}

Returns:

Promise<void>

sandbox()

sandbox(
   idOrHandle: string | SandboxHandleJSON,
   options: SandboxConnectOptions = {}): Sandbox;

Lazily rehydrate a sandbox handle without fetching.

Parameters:

idOrHandle string | SandboxHandleJSON
options SandboxConnectOptions = {}

Returns:

Sandbox

search()

search(options: SearchSandboxesOptions = {}): Promise<SearchResult<Sandbox>>;

Search sandboxes across every region through the search index (GET /sandboxes/search).

Every option is optional and they combine as AND. q is free text over name and image (or an exact id); namePrefix/idPrefix are the server-side form of list({ name })/list({ id }); status, vmClass and region accept a single value or a list (any-of; lifecycle states use the API's wire names such as running); labels is a containment match; the min*/max* and *After/*Before bounds are inclusive, timestamps as RFC 3339 strings or Date objects. sort defaults to created_at and order to desc; limit is clamped to 1..200 by the server. Resolves to a SearchResult whose items are the same Sandbox handles list returns.

Consistency: the index is eventually consistent. A committed create, update or delete becomes searchable about 2-3 s later, so a sandbox you just created may not be in the result yet — use get or list without search filters for read-your-writes. Results span every region, not only the one this API host serves. partialRegions lists region slugs whose cell has not finished backfilling the index (or has never reported in); results for them may be incomplete. It is empty in steady state.

Cursor: nextCursor is opaque and bound to the exact filter and sort that produced it — presenting it with a different filter or sort is a 400, never a silent reset. Paging is best-effort under concurrent mutation: each page reads the live index, so a sandbox whose sort field (status, name, mem_mib, updated_at, ...) changes between two page fetches can appear on both pages or on neither, and creates or deletes mid-walk shift later pages.

Errors: 400 (BadRequestError) for a malformed or mismatched cursor, an unknown status/vmClass/sort value, a non-object labels or a min above its max; 501 (SearchNotConfiguredError with code === 'SEARCH_NOT_CONFIGURED') when this API host has search disabled; 503 (SearchUnavailableError with code === 'SEARCH_UNAVAILABLE') when the index did not answer. The server body is the unified envelope { code, message, source, trace_id } — the class is dispatched from (source, code). On 501/503 callers may fall back to list without search options, which never touches the index.

Parameters:

options SearchSandboxesOptions = {}

Returns:

Promise<SearchResult<Sandbox>>

start()

start(
   sandbox: Sandbox | string,
   options: { readonly timeout?: number } = {}): Promise<void>;

Parameters:

sandbox Sandbox | string
options { readonly timeout?: number } = {}

Returns:

Promise<void>

stop()

stop(sandbox: Sandbox | string): Promise<void>;

Parameters:

sandbox Sandbox | string

Returns:

Promise<void>

updateNetworkPolicy()

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

Parameters:

sandbox Sandbox | string
networkPolicy NetworkPolicyInput
options { ifMatch: string }

Returns:

Promise<NetworkPolicyInfo>

idempotencyKeyForName

function idempotencyKeyForName(name: string): Promise<string>;

The idempotency key create*({ name }) derives when none is given.

'name:' + name when that is a key the API accepts verbatim — printable ASCII (0x20–0x7E), no surrounding whitespace (the API trims keys and HTTP strips header padding, so a padded name would not round-trip), at most 256 characters in total — else 'name:sha256:' + hex(sha256(name)) over the UTF-8 bytes. The name: namespace keeps a derived key from ever colliding with a caller's explicit key of the same spelling. Deterministic and identical in the Python SDK, so the two SDKs are one client to the API's cell-scoped create ledger: use it to recover or inspect the key behind a named create.

OtelApiLike

Structural subset of @opentelemetry/api the SDK uses. Pass your app's import * as otel from '@opentelemetry/api' as otelApi to skip the SDK's own module resolution (required in bundled browser apps).

Properties:

trace { getTracer(name: string, version: string): OtelTracerLike; setSpan(context: OtelContextLike, span: OtelSpanLike): OtelContextLike }
context { active(): OtelContextLike }
propagation { inject(context: OtelContextLike, carrier: OtelCarrier): void }
SpanKind { readonly CLIENT: number }
SpanStatusCode { readonly OK: number; readonly ERROR: number }

DaytonaConfig

Properties:

apiUrl? string - Base URL of the Daytona control-plane API.
apiKey? string - Bearer API key for the control plane and toolbox proxy.
jwtToken? string - Signed-in OIDC JWT exchanged lazily for a short-lived workload-plane token.
projectId? string - Project id required with jwtToken; scopes the exchanged platform token.
requestTimeout? number - Per-request HTTP timeout in milliseconds; 0 keeps the transport unbounded.
otelEnabled? boolean - Emit OpenTelemetry spans around SDK HTTP requests when the optional API package is installed.
otelApi? OtelApiLike - Your application's @opentelemetry/api module (import * as otel from '@opentelemetry/api'). Optional in Node, where the SDK resolves the optional peer itself; required for otelEnabled in bundled browser apps.
connectionPoolMaxsize? number - Node-only keep-alive socket pool size for axios-backed HTTP requests.
target? string - Optional target/region label forwarded on sandbox creation.
sharedHub? boolean - When true (default) all Daytona instances with the same identity share one WaitHub. When false each instance gets its own private hub.
events? SandboxEventsConfig - Customise the sandbox-state events hub. undefined uses the defaults.

Resources

Sandbox resources. cpu/memory/disk are the request: what is reserved and billed as a floor. cpuMax/memoryMax/diskMax are the limits: the boot shape and the ceiling, the system cap when omitted. Set each limit equal to its request for a fixed shape. Requests below the platform minimums are raised to them, so a fixed shape below a minimum is refused.

Properties:

cpu? number - CPU cores, fractional allowed.
cpuMax? number - vCPU limit (whole cores).
memory? number - Memory in GiB.
memoryMax? number - Memory limit in GiB.
disk? number - Scratch disk in GiB.
diskMax? number - Scratch disk limit in GiB.
_experimentalGpu? number - Dedicated GPU count. Experimental: may change or be removed without notice; GPU sandboxes require the organization's gpu_sandboxes feature flag.

SnapshotKind

type SnapshotKind = 'full' | 'checkpoint' | (string & {})

VmClass

type VmClass = 'linux' | 'windows' | 'gpu' | 'macos'

SnapshotRef

Properties:

id string
name string | null

CreateRequestBaseOptions

Properties:

name? string
labels? Record<string, string>
ports? PortRequest[]
lifecycle? LifecycleOptions | null - null is accepted and means "no policy", exactly like omitting the key — a JSON config round-trip produces it, and the Python SDK's None (the same argument in the same position) already reads that way.
cpuArch? CpuArch
cpuType? string
target? string - Per-create hierarchy selector (Earth, Geo, Macro or Edge); overrides config.target.
wait? number
createTtl? number
idempotencyKey? string - Identifies this create to the server: a second create() with the same key and request (in the same project and coordinator or cell) returns the sandbox the first one made instead of a new one, so a create whose response was lost can be retried safely. New records reject changed parameters; historical mappings without a stored request digest may replay the original without detecting changes. There is no fleet-global conflict detection across direct cells. Use a fresh key for a different sandbox. A retried create returns no fresh access token; the project API key manages the sandbox as usual. When omitted the SDK mints a random key per call and reports it on SandboxCreateRequestTimeoutError / SandboxCreateConnectionError if the request itself fails before the server answers. The key is sent verbatim; the server rejects a blank key, a key longer than 256 characters, or one with characters outside printable ASCII with 400 BAD_REQUEST (it travels as an HTTP header).

CreateSandboxOptions

Options for Daytona.create.

Visible resources. In burstable sandboxes the guest boots with the burst ceiling (resources.cpuMax / memoryMax, or the deployment cap when omitted), so nproc and /proc/meminfo report that ceiling, not the guaranteed cpu. Tools that size themselves from the CPU count (pytest -n auto, make -j$(nproc)) start one worker per visible CPU. Pass an explicit worker count when you need the guarantee instead of the ceiling.

Properties:

name? string
labels? Record<string, string>
ports? PortRequest[]
lifecycle? LifecycleOptions | null - null is accepted and means "no policy", exactly like omitting the key — a JSON config round-trip produces it, and the Python SDK's None (the same argument in the same position) already reads that way.
cpuArch? CpuArch
cpuType? string
target? string - Per-create hierarchy selector (Earth, Geo, Macro or Edge); overrides config.target.
wait? number
createTtl? number
idempotencyKey? string - Identifies this create to the server: a second create() with the same key and request (in the same project and coordinator or cell) returns the sandbox the first one made instead of a new one, so a create whose response was lost can be retried safely. New records reject changed parameters; historical mappings without a stored request digest may replay the original without detecting changes. There is no fleet-global conflict detection across direct cells. Use a fresh key for a different sandbox. A retried create returns no fresh access token; the project API key manages the sandbox as usual. When omitted the SDK mints a random key per call and reports it on SandboxCreateRequestTimeoutError / SandboxCreateConnectionError if the request itself fails before the server answers. The key is sent verbatim; the server rejects a blank key, a key longer than 256 characters, or one with characters outside printable ASCII with 400 BAD_REQUEST (it travels as an HTTP header).
env? Record<string, string>
envVars? Record<string, string>
resources? Resources
cpu? number
memory? number
disk? number
volumes? VolumeMount[]
secrets? string[]
persistent? boolean
spot? boolean
user? string
networkPolicy? NetworkPolicyInput | null

CreateSandboxFromSnapshotOptions

Properties:

name? string
labels? Record<string, string>
ports? PortRequest[]
lifecycle? LifecycleOptions | null - null is accepted and means "no policy", exactly like omitting the key — a JSON config round-trip produces it, and the Python SDK's None (the same argument in the same position) already reads that way.
cpuArch? CpuArch
cpuType? string
target? string - Per-create hierarchy selector (Earth, Geo, Macro or Edge); overrides config.target.
wait? number
createTtl? number
idempotencyKey? string - Identifies this create to the server: a second create() with the same key and request (in the same project and coordinator or cell) returns the sandbox the first one made instead of a new one, so a create whose response was lost can be retried safely. New records reject changed parameters; historical mappings without a stored request digest may replay the original without detecting changes. There is no fleet-global conflict detection across direct cells. Use a fresh key for a different sandbox. A retried create returns no fresh access token; the project API key manages the sandbox as usual. When omitted the SDK mints a random key per call and reports it on SandboxCreateRequestTimeoutError / SandboxCreateConnectionError if the request itself fails before the server answers. The key is sent verbatim; the server rejects a blank key, a key longer than 256 characters, or one with characters outside printable ASCII with 400 BAD_REQUEST (it travels as an HTTP header).

CreateGpuSandboxOptions

Properties:

name? string
labels? Record<string, string>
ports? PortRequest[]
lifecycle? LifecycleOptions | null - null is accepted and means "no policy", exactly like omitting the key — a JSON config round-trip produces it, and the Python SDK's None (the same argument in the same position) already reads that way.
cpuArch? CpuArch
cpuType? string
target? string - Per-create hierarchy selector (Earth, Geo, Macro or Edge); overrides config.target.
wait? number
createTtl? number
idempotencyKey? string - Identifies this create to the server: a second create() with the same key and request (in the same project and coordinator or cell) returns the sandbox the first one made instead of a new one, so a create whose response was lost can be retried safely. New records reject changed parameters; historical mappings without a stored request digest may replay the original without detecting changes. There is no fleet-global conflict detection across direct cells. Use a fresh key for a different sandbox. A retried create returns no fresh access token; the project API key manages the sandbox as usual. When omitted the SDK mints a random key per call and reports it on SandboxCreateRequestTimeoutError / SandboxCreateConnectionError if the request itself fails before the server answers. The key is sent verbatim; the server rejects a blank key, a key longer than 256 characters, or one with characters outside printable ASCII with 400 BAD_REQUEST (it travels as an HTTP header).
env? Record<string, string>
envVars? Record<string, string>
resources? Resources
cpu? number
memory? number
disk? number
secrets? string[]
gpu? number | readonly string[]
user? string

CreateGpuSandboxFromSnapshotOptions

Properties:

name? string
labels? Record<string, string>
ports? PortRequest[]
lifecycle? LifecycleOptions | null - null is accepted and means "no policy", exactly like omitting the key — a JSON config round-trip produces it, and the Python SDK's None (the same argument in the same position) already reads that way.
cpuArch? CpuArch
cpuType? string
target? string - Per-create hierarchy selector (Earth, Geo, Macro or Edge); overrides config.target.
wait? number
createTtl? number
idempotencyKey? string - Identifies this create to the server: a second create() with the same key and request (in the same project and coordinator or cell) returns the sandbox the first one made instead of a new one, so a create whose response was lost can be retried safely. New records reject changed parameters; historical mappings without a stored request digest may replay the original without detecting changes. There is no fleet-global conflict detection across direct cells. Use a fresh key for a different sandbox. A retried create returns no fresh access token; the project API key manages the sandbox as usual. When omitted the SDK mints a random key per call and reports it on SandboxCreateRequestTimeoutError / SandboxCreateConnectionError if the request itself fails before the server answers. The key is sent verbatim; the server rejects a blank key, a key longer than 256 characters, or one with characters outside printable ASCII with 400 BAD_REQUEST (it travels as an HTTP header).

CreateWindowsSandboxOptions

Properties:

name? string
labels? Record<string, string>
ports? PortRequest[]
lifecycle? LifecycleOptions | null - null is accepted and means "no policy", exactly like omitting the key — a JSON config round-trip produces it, and the Python SDK's None (the same argument in the same position) already reads that way.
cpuArch? CpuArch
cpuType? string
target? string - Per-create hierarchy selector (Earth, Geo, Macro or Edge); overrides config.target.
wait? number
createTtl? number
idempotencyKey? string - Identifies this create to the server: a second create() with the same key and request (in the same project and coordinator or cell) returns the sandbox the first one made instead of a new one, so a create whose response was lost can be retried safely. New records reject changed parameters; historical mappings without a stored request digest may replay the original without detecting changes. There is no fleet-global conflict detection across direct cells. Use a fresh key for a different sandbox. A retried create returns no fresh access token; the project API key manages the sandbox as usual. When omitted the SDK mints a random key per call and reports it on SandboxCreateRequestTimeoutError / SandboxCreateConnectionError if the request itself fails before the server answers. The key is sent verbatim; the server rejects a blank key, a key longer than 256 characters, or one with characters outside printable ASCII with 400 BAD_REQUEST (it travels as an HTTP header).
env? Record<string, string>
envVars? Record<string, string>
resources? Resources
cpu? number
memory? number
disk? number
secrets? string[]
persistent? boolean
spot? boolean

LifecycleOptions

Per-sandbox lifecycle policy: a wall-clock timeout and an idle timeout, each paired with the action it fires.

timeoutSecs (>= 1, never disabled) fires onTimeout that many seconds after create, after a setLifecycle() that supplies it, and again after every accepted transition to running (start, resume, wake) — the full budget re-arms each time. Omitted onTimeout resolves to the class default (pause linux persistent, stop windows persistent, delete ephemeral and gpu).

idleTimeoutSecs is opt-in and fires onIdleTimeout after that many seconds without activity; DISABLED clears it. onIdleTimeout has no default — arming idleTimeoutSecs from nothing requires it.

At create, each field you omit is inherited: first from the project's lifecycle defaults (set in the dashboard's project settings; a persistent sandbox uses the persistent defaults, every other sandbox the ephemeral ones), then — for timeoutSecs only — from the platform default timeout when the platform has it enabled. An action follows its own interval: a timeoutSecs you pass without onTimeout gets the class default, not the project's action. Pass DISABLED as idleTimeoutSecs to opt out of an inherited idle timeout. Project defaults apply to new sandboxes only; setLifecycle() never consults them.

Rejected before posting when inapplicable to the sandbox class: see LifecycleAction for the action matrix; wakeOnRequest needs linux persistent.

Properties:

timeoutSecs? number
onTimeout? LifecycleAction
idleTimeoutSecs? number
onIdleTimeout? LifecycleAction
wakeOnRequest? boolean

SandboxConnectOptions

Properties:

toolboxUrl? string - Direct daemon URL for this sandbox, or proxy URL already scoped to it.
accessToken? string - Token override for this sandbox's daemon/proxy. A caller-supplied token is used verbatim and never silently replaced: its expiry surfaces as a 401. Without one, a handle with a control-plane API key mints and refreshes short-lived sandbox access tokens transparently.
autoDelete? boolean - Auto-delete when disposed with await using; defaults to false for rehydrated handles.

ListResult

Properties:

items T[]
nextCursor? string
total? number - Only set when the page came from the search index (Daytona.list() with a search filter).
totalRelation? string - 'eq' when total is exact, 'gte' when it is a lower bound; only set with total.
partialRegions? string[] - Region slugs whose index is still backfilling; only set when the page came from the search index.

NetworkPolicyInput

Properties:

blockAll? boolean | null
allowCidrs? string[]
allowDomains? string[] | null

NetworkPolicy

Properties:

version number
blockAll boolean
allowCidrs string[]
allowDomains string[] | null

NetworkPolicyInfo

Properties:

desired? NetworkPolicy
desiredRevision number
etag string
httpStatus number
applied? NetworkPolicy
appliedRevision? number
appliedIncarnation? string
state? string
failureReason? string

CpuArch

type CpuArch = 'amd64' | 'arm64'

CpuTypeInfo

Properties:

id string
name string
cpuArch CpuArch

NetworkClassInfo

Properties:

id string
name string

DiskClassInfo

Properties:

id string
name string

AuditScenarios

type AuditScenarios = Schema<"AuditScenarios">

AuditTargetScenario

type AuditTargetScenario = Schema<"AuditTargetScenario">

CurrentApiKey

type CurrentApiKey = Schema<"CurrentApiKey">

ProjectBudget

type ProjectBudget = Schema<"ProjectBudget">

VmStateSnapshot

type VmStateSnapshot = api.SnapshotRow

SnapshotDetail

type SnapshotDetail = api.SnapshotRow

GET /snapshots/{id} detail row.

VmDto

Properties:

id string
class? string - Sandbox class (linux | windows | gpu | macos); the authoritative class when present.
name? string
image? api.VmArtifactRef | null
manifest_name? string | null
runner_id? string | null
status? string
cpu? number
vcpus? number
vcpus_max? number | null
mem_mib? number
mem_max_mib? number | null
scratch_mib? number
scratch_max_mib? number | null
error? string | null
labels? unknown
spot? boolean
spot_evicted_at? string | null
toolboxProxyUrl? string
toolbox_proxy_url? string
region? string
gpu_host_count? number
image_build_id? string | null
os_family? 'linux' | 'windows' | 'macos' | string | null
windows_image? string | null
user? string | null
snapshot? api.VmArtifactRef | null
mac_boot_mode? string | null - macOS only: set on the running that ends a resume; null otherwise.
persistent? boolean - Absent on the batch-wait (?ids=) read shape, which returns a bare row.
lifecycle? SandboxLifecycleDto
capabilities? SandboxCapabilities
created_at? string - Present on GET /sandboxes/search items (PLAN-SANDBOX-SEARCH-INDEX §4.2); 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.

ListSandboxesOptions

Every Daytona.list() option. cursor/limit/id/name keep the region-local GET /sandboxes semantics; any inherited search filter routes the call to /sandboxes/search.

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.
persistent? boolean
spot? boolean
forkedFrom? string - Sandboxes forked from this sandbox id.
minVcpus? number
maxVcpus? number
minMemMib? number
maxMemMib? number
minScratchMib? number
maxScratchMib? number
createdAfter? SearchTimestamp
createdBefore? SearchTimestamp
updatedAfter? SearchTimestamp
updatedBefore? SearchTimestamp
lastActiveAfter? SearchTimestamp
lastActiveBefore? SearchTimestamp
sort? SearchSort - Defaults to created_at.
order? SearchOrder - Defaults to desc.
cursor? string
limit? number
id? string - Prefix on the id.
name? string - Prefix on the name.

ListSandboxesQuery

type ListSandboxesQuery = ListSandboxesOptions

CreateMacosSandboxOptions

Options for a macOS create (POST /sandboxes/macos). The Mac sets the size (half of it per sandbox), so there is no cpu, memory or disk; network policy and CPU selectors do not apply.

Extends: Omit<CreateRequestBaseOptions, 'cpuArch' | 'cpuType'>

Properties:

env? Record<string, string>
envVars? Record<string, string>
persistent? boolean - Stop checkpoints the disk and Start restores it; pause keeps memory.
reservation? 'new' | (string & {}) - Which Mac lease the sandbox runs on. Omitted: the server packs it onto a reserved Mac with room, and when none has room buys a new lease if the organization's auto-reserve setting allows it. 'new': always buy a new lease for this sandbox. Any other value is a reservation id as reservations.list() returns it: place the sandbox on exactly that lease.
autoRenew? boolean - Only with reservation: 'new': whether the bought lease renews itself each period. The server defaults it to the organization's auto-reserve setting. Rejected before posting otherwise.

NAME_LABEL

const NAME_LABEL = 'name'

The label every create*({ name }) stamps with the name (issue #1935): labels == { name, … }. Daytona.findByName reads it back.

DISABLED

const DISABLED = -1

Clears LifecycleOptions.idleTimeoutSecs — and ONLY that field.

idleTimeoutSecs value space, identical at create and on sandbox.setLifecycle(): omitted = unchanged (setLifecycle) / disabled (create); DISABLED (-1) = clear the idle pair (onIdleTimeout with it); n > 0 = seconds, a value below 60 raised to 60 server-side and read back raised; 0 and anything below -1 are rejected.

timeoutSecs does NOT accept it: the timeout cannot be disabled, so timeoutSecs must be >= 1 (-1 and 0 are rejected).

LifecycleAction

const LifecycleAction = ["stop","pause","delete"] as const

On this page

Computersfor Agents