Daytona v2

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

Daytona

Constructors

Constructor

new Daytona(config: DaytonaConfig = {}, internal: InternalOptions = {}): Daytona;

Parameters:

• config DaytonaConfig = {}
• internal InternalOptions = {}

Returns:

• Daytona

Methods

[Symbol.asyncDispose]()

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

await using daytona = new Daytona() calls close() at the end of the scope.

Returns:

• Promise<void>

close()

close(): Promise<void>;

Close the namespace clients built so far: the v2 client (its sandbox-state events socket) and the v0 client (its event socket and, with otelEnabled, its OpenTelemetry SDK, through v0’s [Symbol.asyncDispose]()). Optional for short scripts — neither keeps a Node process alive — but long-running processes should call it. Idempotent; a later root.v0 / root.v2 builds a fresh client. Both are closed even if one fails; the first error is re-thrown (Python parity).

Returns:

• Promise<void>

v0

get v0(): DaytonaV0Client;

The v0 namespace: the v0 SDK’s own Daytona client (the 0.x SDK bundled at a pinned release), the same instance on every access. Built on first access, which loads the v0 SDK synchronously in Node (about 100 ms, once per process); Node code that only uses v2 never loads it. Browser builds bundle the v0 SDK statically into apps that import the root and evaluate it when the root loads, so daytona.v0 works there too. A failed load is not cached: the next access retries.

Returns:

• DaytonaV0Client

v2

get v2(): DaytonaV2Client;

Returns:

• DaytonaV2Client

---

DaytonaV2Client

Properties:

• images ImagesService
• snapshots SnapshotsService
• secret SecretService
• reservations ReservationsService
• macModels MacModelsService - The Mac model registry that reservations.create({ model }) draws from.

Methods

archive()

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

Parameters:

• sandbox Sandbox | string

Returns:

• Promise<void>

close()

close(): Promise<void>;

Returns:

• Promise<void>

create()

create(): Promise<Sandbox>;

Create a Linux sandbox from a registered image name or img_… id.

Omitting the image (create() or create(options)) boots the platform default image, the Linux image the operator marks as default (images.list({ platform: 'true' }) shows it with default: true). When no default is configured the create fails with DEFAULT_IMAGE_NOT_CONFIGURED (400). An empty or whitespace-only image is still an error, thrown before any request.

Returns:

• Promise<Sandbox>

create()

create(image: string | undefined, options?: CreateSandboxOptions): Promise<Sandbox>;

Parameters:

• image string | undefined
• options? CreateSandboxOptions

Returns:

• Promise<Sandbox>

create()

create(options: CreateSandboxOptions): Promise<Sandbox>;

Parameters:

• options CreateSandboxOptions

Returns:

• Promise<Sandbox>

create()

create(
   imageOrOptions?: string | CreateSandboxOptions,
   maybeOptions?: CreateSandboxOptions): Promise<Sandbox>;

Parameters:

• imageOrOptions? string | CreateSandboxOptions
• maybeOptions? 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. region 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 region.

Parameters:

• builder ImageBuilder
• options CreateSandboxOptions & Omit<BuildImageOptions, ‘region’> = {}

Returns:

• Promise<Sandbox>

createFromSnapshot()

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

Create a sandbox from a snapshot.

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 Mac reservation: omitted uses any fitting reservation of the organization in the region (or lets the organization’s auto-reserve buy one), 'new' buys a reservation of the cheapest model that fits, and a reservation id targets that reservation at claim. With no reservation to use it fails with ConflictError (NO_ACTIVE_RESERVATION, NO_FREE_SLOT, MAC_DISK_FULL, AUTO_RESERVE_LIMIT_REACHED, NO_MAC_AVAILABLE). cpu (whole vCPUs), memory (GiB) and disk (GiB) size the sandbox; each omitted axis uses half of the claiming Mac, rounded down, on a split reservation, or all of it on a whole reservation. The first successful claim fixes the size, which the sandbox reports from then on. name, idempotencyKey, waitSeconds and createTimeoutSeconds behave as on create. networkPolicy sets the egress policy as on create; a sandbox with a policy runs only on a Mac that can enforce it.

Creating macOS sandboxes requires the organization’s macos_sandboxes feature capability; without it the API answers 403 FEATURE_NOT_ENABLED (thrown as FeatureNotEnabledError).

macOS sandboxes are served by the macOS API cell, not the default https://api.daytona.com: set DAYTONA_V2_API_URL=https://api.us-macos.daytona.com before creating the client. Against the default API the create throws ConflictError naming that setting; the SDK does not reroute.

Parameters:

• image string
• options CreateMacosSandboxOptions = {}

Returns:

• Promise<Sandbox>

currentApiKey()

currentApiKey(): Promise<api.ProjectApiKeyWithContext>;

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

delete()

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

Parameters:

• sandbox Sandbox | string

Returns:

• Promise<void>

findByName()

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

Find the sandbox created with { name }.

Uses the exact labels.name value every create*({ name }) stamps. 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. The lookup goes through sandbox search, which indexes a new sandbox shortly after its create, and a deployment without search answers SearchNotConfiguredError (501).

region scopes the read the way it scopes a create, 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 { region?: 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>;

Return the monthly spend budget of the API key’s project. An unset budget has nullable limit and period fields. The key needs read:spending. 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>

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 and totalRelation on the result. That path is eventually consistent: a committed change is searchable after roughly 2-3 s and it spans every region rather than only this API host’s. 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>>

listAuditActions()

listAuditActions(): Promise<api.AuditActionList>;

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

Returns:

• Promise<api.AuditActionList>

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>

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* bounds are inclusive, the *StartAt timestamp bounds are inclusive and the *EndAt bounds are exclusive, timestamps as RFC 3339 strings or Date objects (a Date is serialized in UTC — a whole day is createdStartAt that day and createdEndAt the next). 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.

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, memory_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.

---

DaytonaV0Client

type DaytonaV0Client = InstanceType<V0ModuleTypes['RootOnlyClientV0']>

The v0 SDK’s own Daytona instance type: what daytona.v0 returns. The bundle exports the class under the private RootOnlyClientV0, read only here (#3520): SDK 2.x builds a v0 client only through the root.

---

DaytonaConfig

type DaytonaConfig = {
  readonly apiKey?: string
  readonly jwtToken?: string
  /** v0 only: scopes a JWT to an organization. */
  readonly organizationId?: string
  /**
   * The v0 client's default region (`v2` takes a per-create `region`).
   * @deprecated Applies only to the v0 namespace. Pass `target` per v0 sandbox
   * create (`d.v0.create({ target })`) or `regionId` per v0 snapshot create
   * instead. Setting it still works and emits a runtime deprecation warning.
   */
  readonly target?: string
  /** v2 only: scopes a JWT to a project. */
  readonly projectId?: string
  /** v2 only. */
  readonly requestTimeout?: number
  /** Both namespaces. */
  readonly otelEnabled?: boolean
  /** v2 only. */
  readonly otelApi?: OtelApiLike
  /** v2 only (v0 at the pinned release has no pool-size setting). */
  readonly connectionPoolMaxsize?: number
  /** v2 only: share the sandbox-state events hub with matching clients (default `true`). */
  readonly sharedHub?: boolean
  /** v2 only: sandbox-state events hub settings (`SandboxEventsConfig` from `@daytona/sdk/v2`). */
  readonly events?: SandboxEventsConfig
}

Configuration shared by both namespaces. Routing per field (also ROOT_CONFIG_ROUTING): apiKey, jwtToken, otelEnabled reach v0 and v2; organizationId and the deprecated target are v0-only; projectId, requestTimeout, otelApi, connectionPoolMaxsize, sharedHub and events are v2-only.

Properties:

• apiKey? string
• jwtToken? string
• organizationId? string - v0 only: scopes a JWT to an organization.
• target? string - The v0 client’s default region (v2 takes a per-create region).
• projectId? string - v2 only: scopes a JWT to a project.
• requestTimeout? number - v2 only.
• otelEnabled? boolean - Both namespaces.
• otelApi? OtelApiLike - v2 only.
• connectionPoolMaxsize? number - v2 only (v0 at the pinned release has no pool-size setting).
• sharedHub? boolean - v2 only: share the sandbox-state events hub with matching clients (default true).
• events? SandboxEventsConfig - v2 only: sandbox-state events hub settings (SandboxEventsConfig from @daytona/sdk/v2).

---

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 }

---

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.

---

SnapshotKind

type SnapshotKind = (typeof API_SNAPSHOT_KINDS)[number] | 'unknown'

---

VmClass

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

---

SnapshotRef

Properties:

• id string
• name string | null

---

CreateRequestBaseOptions

Properties:

• name? string
• labels? Record<string, string>
• ports? PortMapping[]
• lifecyclePolicy? LifecyclePolicyOptions | 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
• region? string - Per-create hierarchy selector (Earth, Geo, Macro or Edge).
• waitSeconds? number
• createTimeoutSeconds? 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? PortMapping[]
• lifecyclePolicy? LifecyclePolicyOptions | 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
• region? string - Per-create hierarchy selector (Earth, Geo, Macro or Edge).
• waitSeconds? number
• createTimeoutSeconds? 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[]
• spot? boolean
• user? string
• networkPolicy? NetworkPolicyInput | null

---

LifecycleAction

type LifecycleAction = 'stop' | 'pause' | 'delete'

The action a lifecycle trigger fires: onTimeout / onIdleTimeout.

Legal per class: delete everywhere; stop needs a persistent sandbox (linux or windows — never gpu, which is always ephemeral); pause needs linux persistent.

---

CreateSandboxFromSnapshotOptions

Properties:

• name? string
• labels? Record<string, string>
• ports? PortMapping[]
• lifecyclePolicy? LifecyclePolicyOptions | 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
• region? string - Per-create hierarchy selector (Earth, Geo, Macro or Edge).
• waitSeconds? number
• createTimeoutSeconds? 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).

---

LifecyclePolicyOptions

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

timeoutSeconds (>= 1, never disabled) fires onTimeout after that many seconds after create, after an updateLifecyclePolicy() 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).

idleExpirySeconds is opt-in and fires onIdleTimeout after that many seconds without activity; DISABLED clears it. onIdleTimeout has no default — arming idleExpirySeconds 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 timeoutSeconds only — from the platform default timeout when the platform has it enabled. An action follows its own interval: a timeoutSeconds you pass without onTimeout gets the class default, not the project’s action. Pass DISABLED as idleExpirySeconds to opt out of an inherited idle timeout. Project defaults apply to new sandboxes only; updateLifecyclePolicy() never consults them.

archiveIntervalSeconds is how long a stopped sandbox waits before it is archived: its disk moves to object storage, and its next start restores it first. 60 to 2592000 (30 days); 0 means the maximum. Project defaults do not set it: omitted at create, the platform default (one day) applies.

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

Properties:

• timeoutSeconds? number
• onTimeout? LifecycleAction
• idleExpirySeconds? number
• onIdleTimeout? LifecycleAction
• wakeOnRequest? boolean
• archiveIntervalSeconds? number

---

SandboxConnectOptions

Properties:

• toolboxUrl? string - Direct daemon URL for this sandbox, or proxy URL already scoped to it. The SDK sends this sandbox’s toolbox credential there (the API key, a project token, or a minted sandbox token), so pass only a URL you trust — never one read from stored or user-supplied data. Omit it to use the URL the control plane returns.
• 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.

---

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? SearchTotalRelation - 'eq' when total is exact, 'gte' when it is a lower bound; only set with total.
• rawTotalRelation? string

---

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
• appliedStartId? string
• status? string
• error? 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

---

AuditActionList

type AuditActionList = api.AuditActionList

---

AuditActionGroup

type AuditActionGroup = api.AuditActionGroup

---

ProjectApiKeyWithContext

type ProjectApiKeyWithContext = api.ProjectApiKeyWithContext

---

ProjectBudget

type ProjectBudget = api.ProjectBudget

---

VmStateSnapshot

type VmStateSnapshot = api.SnapshotRow

---

SnapshotDetail

type SnapshotDetail = api.SnapshotRow

GET /snapshots/{id} detail row.

---

VmDto

Properties:

• id string
• class? VmClass | string - Sandbox class (linux | windows | gpu | macos); the authoritative class when present.
• name? string
• image? api.ImageReference | null
• status? string
• cpu? number
• vcpus? number
• memory_mib? number
• memory_max_mib? number | null
• disk_mib? number
• disk_max_mib? number | null
• error? string | null
• labels? unknown
• spot? boolean | null
• vcpus_max? number | null
• spot_evicted_at? string | null
• toolboxProxyUrl? string
• toolbox_proxy_url? string | null
• region? string
• gpu_count? number | null
• 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 by the current or latest successful claim. GET /sandboxes/search items omit it.
• persistent? boolean | null - Absent on GET /sandboxes/batch-wait items, which are built from the bare row.
• archived? boolean | null - Absent on GET /sandboxes/batch-wait items and on search items.
• lifecycle_policy? SandboxLifecycleDto | null
• capabilities? SandboxCapabilities
• created_at? string | null - 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.
• 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.
• 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). cpu, memory and disk size the sandbox; each omitted axis uses the claiming Mac’s share. CPU selectors do not apply.

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

Properties:

• env? Record<string, string>
• envVars? Record<string, string>
• secrets? string[] - Project secret names to attach, as on create: the sandbox sees a placeholder in each named variable, and the Mac’s egress proxy puts the real value in HTTPS requests to the secret’s allowed domains. Needs the read:secrets permission.
• cpu? number - Whole vCPUs, at least 4; sent as vcpus. Omitted uses half of the claiming Mac, rounded down.
• memory? number - Memory in GiB, at least 4; sent as memory_mib. memory * 1024 must be an integer. Omitted uses half of the claiming Mac, rounded down.
• disk? number - Disk in GiB, at least 80; sent as disk_mib. The whole guest disk, macOS included. disk * 1024 must be an integer. Omitted uses half of the claiming Mac’s sandbox disk room, rounded down to a whole GiB, on a split reservation, or all of it on a whole reservation.
• persistent? boolean - Stop keeps the disk on the same Mac. Start and resume use that Mac. Delete erases the disk. At reservation end, the disk is saved as an anonymous image before the Mac is erased; a lost Mac saves it if it comes back within 7 days. If a Mac restarts before it is declared lost, a running persistent sandbox comes back stopped with its disk, a running ephemeral sandbox is lost, and stopped and paused sandboxes are unchanged. Create a sandbox from an image to continue on another Mac.
• reservation? ‘new’ | (string & {}) - Which Mac reservation the sandbox runs on. Omitted: any fitting reservation of the organization in the region; when none fits and the organization’s auto-reserve setting allows it, the server buys a reservation. 'new': buy a reservation of the cheapest model that fits. Any other value is a reservation id as reservations.list() returns it. A reservation ID targets that reservation at claim. Acceptance does not reserve room; the sandbox can wait for room or time out.
• autoRenew? boolean - Only with reservation: 'new': whether the bought reservation renews itself each period. The server defaults it to the organization’s auto-reserve setting. Rejected before posting otherwise.
• networkPolicy? NetworkPolicyInput | null - Egress policy, as on create: the Mac enforces it from the guest’s first boot, and a sandbox with a policy runs only on a Mac that can enforce it (otherwise the API answers 503). Change it later with sandbox.updateNetworkPolicy.

---

DEFAULT_V2_API_URL

const DEFAULT_V2_API_URL = 'https://api.daytona.com'

The production v2 API (the central API), used when neither DAYTONA_V2_API_URL nor DAYTONA_API_URL is set.

---

V0_API_URL

const V0_API_URL = 'https://app.daytona.io/api'

---

DEFAULT_V2_API_URL

export { DEFAULT_V2_API_URL as DEFAULT_V2_API_URL }

Alias of DEFAULT_V2_API_URL.

---

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 LifecyclePolicyOptions.idleExpirySeconds — and ONLY that field.

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

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