--- title: "Daytona" hideTitleOnPage: true --- ## Daytona ### Constructors #### Constructor ```ts new Daytona(config: DaytonaConfig = {}, internal: InternalOptions = {}): Daytona; ``` **Parameters**: - `config` _DaytonaConfig = \{\}_ - `internal` _InternalOptions = \{\}_ **Returns**: - `Daytona` ### Methods #### \[Symbol.asyncDispose\]() ```ts [Symbol.asyncDispose](): Promise; ``` `await using daytona = new Daytona()` calls `close()` at the end of the scope. **Returns**: - `Promise` #### close() ```ts close(): Promise; ``` 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` #### v0 ```ts 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 ```ts 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() ```ts archive(sandbox: Sandbox | string): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ **Returns**: - `Promise` #### close() ```ts close(): Promise; ``` **Returns**: - `Promise` #### create() ```ts create(): Promise; ``` 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. Creating Linux sandboxes requires the organization's `v2_linux_sandboxes` feature flag: a caller holding `write:sandboxes` in an organization without it gets `403` `FEATURE_NOT_ENABLED` (thrown as `FeatureNotEnabledError`). **Returns**: - `Promise` #### create() ```ts create(image: string | undefined, options?: CreateSandboxOptions): Promise; ``` **Parameters**: - `image` _string \| undefined_ - `options?` _CreateSandboxOptions_ **Returns**: - `Promise` #### create() ```ts create(options: CreateSandboxOptions): Promise; ``` **Parameters**: - `options` _CreateSandboxOptions_ **Returns**: - `Promise` #### create() ```ts create( imageOrOptions?: string | CreateSandboxOptions, maybeOptions?: CreateSandboxOptions): Promise; ``` **Parameters**: - `imageOrOptions?` _string \| CreateSandboxOptions_ - `maybeOptions?` _CreateSandboxOptions_ **Returns**: - `Promise` #### createFromBuild() ```ts createFromBuild( builder: ImageBuilder, options: CreateSandboxOptions & Omit = {}): Promise; ``` 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\ = \{\}_ **Returns**: - `Promise` #### createFromSnapshot() ```ts createFromSnapshot( snapshot: string, options: CreateSandboxFromSnapshotOptions = {}): Promise; ``` Create a sandbox from a snapshot. Creating Linux sandboxes requires the organization's `v2_linux_sandboxes` feature flag: a caller holding `write:sandboxes` in an organization without it gets `403` `FEATURE_NOT_ENABLED` (thrown as `FeatureNotEnabledError`). **Parameters**: - `snapshot` _string_ - `options` _CreateSandboxFromSnapshotOptions = \{\}_ **Returns**: - `Promise` #### createMacos() ```ts createMacos(image: string, options: CreateMacosSandboxOptions = {}): Promise; ``` 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` (cores), `memory` (GiB) and `disk` (GiB) size the sandbox; each omitted axis uses half of the claiming Mac, rounded down, on a model that runs two sandboxes, or all of it on a model that runs one. 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 API cell of their Mac region, as Linux sandboxes are: for the `bos-1` Macs set `DAYTONA_V2_API_URL=https://api.us-east.daytona.com` before creating the client. An API that does not serve the region answers `ConflictError`; the SDK does not reroute. **Parameters**: - `image` _string_ - `options` _CreateMacosSandboxOptions = \{\}_ **Returns**: - `Promise` #### currentApiKey() ```ts currentApiKey(): Promise; ``` 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` #### delete() ```ts delete(sandbox: Sandbox | string): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ **Returns**: - `Promise` #### findByName() ```ts findByName(name: string, options: { region?: string } = {}): Promise; ``` 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` #### get() ```ts get(id: string, options: SandboxConnectOptions = {}): Promise; ``` Fetch a sandbox by id. **Parameters**: - `id` _string_ - `options` _SandboxConnectOptions = \{\}_ **Returns**: - `Promise` #### getLimits() ```ts getLimits(options: GetLimitsOptions = {}): Promise; ``` Return the organization's limits and current usage. A null `limit` means unlimited. With an API key the organization defaults to the key's own, looked up once and cached; with `jwtToken` authentication pass `organizationId`. The credential needs `read:limits`. Member counts (`members`) are not included: they are served to signed-in members only. **Parameters**: - `options` _GetLimitsOptions = \{\}_ **Returns**: - `Promise` #### getNetworkPolicy() ```ts getNetworkPolicy(sandbox: Sandbox | string): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ **Returns**: - `Promise` #### getProjectBudget() ```ts getProjectBudget(): Promise; ``` 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` #### getSandboxSecrets() ```ts getSandboxSecrets(sandbox: Sandbox | string): Promise; ``` Read a sandbox's attached secret names and apply state; see `Sandbox.getSecrets`. **Parameters**: - `sandbox` _Sandbox \| string_ **Returns**: - `Promise` #### iter() ```ts iter(options: ListSandboxesOptions = {}): AsyncIterable; ``` **Parameters**: - `options` _ListSandboxesOptions = \{\}_ **Returns**: - `AsyncIterable` #### list() ```ts list(options: ListSandboxesOptions = {}): Promise>; ``` List sandboxes as one page `{ items, nextCursor }`. With only `cursor`/`limit` this is the read-your-writes path: one page of `GET /sandboxes`, newest first. A sandbox you just created is in the result; walk further pages with `iter` or the returned cursor. Through the shared API router the list spans every region, and a region that does not answer fails the call with 503 (`ServiceUnavailableError`) rather than returning a list without its sandboxes; against one region's own API URL it lists that region only. 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>` #### listAuditActions() ```ts listAuditActions(): Promise; ``` Return the actions the audit log can record for each target type. **Returns**: - `Promise` #### pause() ```ts pause( sandbox: Sandbox | string, options: { readonly timeout?: number } = {}): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ - `options` _\{ readonly timeout?: number \} = \{\}_ **Returns**: - `Promise` #### replaceSandboxSecrets() ```ts replaceSandboxSecrets( sandbox: Sandbox | string, secrets: readonly string[], options: { ifMatch: string }): Promise; ``` Replace a sandbox's attached secret names; see `Sandbox.replaceSecrets`. **Parameters**: - `sandbox` _Sandbox \| string_ - `secrets` _readonly string\[\]_ - `options` _\{ ifMatch: string \}_ **Returns**: - `Promise` #### resetNetworkPolicy() ```ts resetNetworkPolicy( sandbox: Sandbox | string, options: { ifMatch: string }): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ - `options` _\{ ifMatch: string \}_ **Returns**: - `Promise` #### resume() ```ts resume( sandbox: Sandbox | string, options: { readonly timeout?: number } = {}): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ - `options` _\{ readonly timeout?: number \} = \{\}_ **Returns**: - `Promise` #### search() ```ts search(options: SearchSandboxesOptions = {}): Promise>; ``` 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>` #### start() ```ts start( sandbox: Sandbox | string, options: { readonly timeout?: number } = {}): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ - `options` _\{ readonly timeout?: number \} = \{\}_ **Returns**: - `Promise` #### stop() ```ts stop(sandbox: Sandbox | string): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ **Returns**: - `Promise` #### updateNetworkPolicy() ```ts updateNetworkPolicy( sandbox: Sandbox | string, networkPolicy: NetworkPolicyInput, options: { ifMatch: string }): Promise; ``` **Parameters**: - `sandbox` _Sandbox \| string_ - `networkPolicy` _NetworkPolicyInput_ - `options` _\{ ifMatch: string \}_ **Returns**: - `Promise` *** ## idempotencyKeyForName ```ts function idempotencyKeyForName(name: string): Promise; ``` 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 ```ts type DaytonaV0Client = InstanceType ``` 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 ```ts 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 ```ts type SnapshotKind = (typeof API_SNAPSHOT_KINDS)[number] | 'unknown' ``` *** ## VmClass ```ts type VmClass = 'linux' | 'windows' | 'gpu' | 'macos' ``` *** ## SnapshotRef **Properties**: - `id` _string_ - `name` _string \| null_ *** ## CreateRequestBaseOptions **Properties**: - `name?` _string_ - `labels?` _Record\_ - `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\_ - `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\_ - `envVars?` _Record\_ - `resources?` _Resources_ - `cpu?` _number_ - `memory?` _number_ - `disk?` _number_ - `secrets?` _string\[\]_ - `spot?` _boolean_ - `user?` _string_ - `networkPolicy?` _NetworkPolicyInput \| null_ *** ## LifecycleAction ```ts 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\_ - `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 ```ts 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 ```ts type AuditActionList = api.AuditActionList ``` *** ## AuditActionGroup ```ts type AuditActionGroup = api.AuditActionGroup ``` *** ## ProjectApiKeyWithContext ```ts type ProjectApiKeyWithContext = api.ProjectApiKeyWithContext ``` *** ## ProjectBudget ```ts type ProjectBudget = api.ProjectBudget ``` *** ## VmStateSnapshot ```ts type VmStateSnapshot = api.SnapshotRow ``` *** ## SnapshotDetail ```ts 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` alone read `GET /sandboxes`; `id`/`name` and any inherited search filter route 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\_ - 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 ```ts 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` **Properties**: - `env?` _Record\_ - `envVars?` _Record\_ - `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_ - CPU cores, at least 4; sent as vcpus. Omitted uses half of the claiming Mac's cores, rounded down, on a model that runs two sandboxes, or all of them on a model that runs one. - `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's memory, rounded down, on a model that runs two sandboxes, or all of it on a model that runs one. - `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 model that runs two sandboxes, or all of it on a model that runs one. - `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`. *** ## OrganizationLimits ```ts type OrganizationLimits = api.OrganizationLimits ``` *** ## GetLimitsOptions Options for `Daytona.getLimits`. **Properties**: - `organizationId?` _string_ - The organization to read. Defaults to the API key's organization; required when the client authenticates with `jwtToken`. *** ## DEFAULT\_V2\_API\_URL ```ts const DEFAULT_V2_API_URL = 'https://api.daytona.com' ``` The production v2 API, used when neither `DAYTONA_V2_API_URL` nor `DAYTONA_API_URL` is set. Each call reaches the cell that owns it only when a cell router serves this hostname (PLAN-CELL-ROUTER.md "The router as the API front door"); the central API itself serves no region. *** ## V0\_API\_URL ```ts const V0_API_URL = 'https://app.daytona.io/api' ``` *** ## DEFAULT\_V2\_API\_URL ```ts export { DEFAULT_V2_API_URL as DEFAULT_V2_API_URL } ``` Alias of `DEFAULT_V2_API_URL`. *** ## NAME\_LABEL ```ts const NAME_LABEL = 'name' ``` The label every `create*({ name })` stamps with the name (issue #1935): `labels == { name, … }`. `Daytona.findByName` reads it back. *** ## DISABLED ```ts 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).