# Daytona

## 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<void>;
```

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

**Returns**:

- `Promise<void>`

#### close()

```ts
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

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

**Parameters**:

- `sandbox` _Sandbox \| string_

**Returns**:

- `Promise<void>`

#### close()

```ts
close(): Promise<void>;
```

**Returns**:

- `Promise<void>`

#### create()

```ts
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()

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

**Parameters**:

- `image` _string \| undefined_
- `options?` _CreateSandboxOptions_

**Returns**:

- `Promise<Sandbox>`

#### create()

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

**Parameters**:

- `options` _CreateSandboxOptions_

**Returns**:

- `Promise<Sandbox>`

#### create()

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

**Parameters**:

- `imageOrOptions?` _string \| CreateSandboxOptions_
- `maybeOptions?` _CreateSandboxOptions_

**Returns**:

- `Promise<Sandbox>`

#### createFromBuild()

```ts
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()

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

Create a sandbox from a snapshot.

**Parameters**:

- `snapshot` _string_
- `options` _CreateSandboxFromSnapshotOptions = \{\}_

**Returns**:

- `Promise<Sandbox>`

#### createMacos()

```ts
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()

```ts
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()

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

**Parameters**:

- `sandbox` _Sandbox \| string_

**Returns**:

- `Promise<void>`

#### findByName()

```ts
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()

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

Fetch a sandbox by id.

**Parameters**:

- `id` _string_
- `options` _SandboxConnectOptions = \{\}_

**Returns**:

- `Promise<Sandbox>`

#### getNetworkPolicy()

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

**Parameters**:

- `sandbox` _Sandbox \| string_

**Returns**:

- `Promise<NetworkPolicyInfo>`

#### getProjectBudget()

```ts
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()

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

**Parameters**:

- `options` _ListSandboxesOptions = \{\}_

**Returns**:

- `AsyncIterable<Sandbox>`

#### list()

```ts
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()

```ts
listAuditActions(): Promise<api.AuditActionList>;
```

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

**Returns**:

- `Promise<api.AuditActionList>`

#### pause()

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

**Parameters**:

- `sandbox` _Sandbox \| string_
- `options` _\{ readonly timeout?: number \} = \{\}_

**Returns**:

- `Promise<void>`

#### resetNetworkPolicy()

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

**Parameters**:

- `sandbox` _Sandbox \| string_
- `options` _\{ ifMatch: string \}_

**Returns**:

- `Promise<NetworkPolicyInfo>`

#### resume()

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

**Parameters**:

- `sandbox` _Sandbox \| string_
- `options` _\{ readonly timeout?: number \} = \{\}_

**Returns**:

- `Promise<void>`

#### search()

```ts
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()

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

**Parameters**:

- `sandbox` _Sandbox \| string_
- `options` _\{ readonly timeout?: number \} = \{\}_

**Returns**:

- `Promise<void>`

#### stop()

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

**Parameters**:

- `sandbox` _Sandbox \| string_

**Returns**:

- `Promise<void>`

#### updateNetworkPolicy()

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

**Parameters**:

- `sandbox` _Sandbox \| string_
- `networkPolicy` _NetworkPolicyInput_
- `options` _\{ ifMatch: string \}_

**Returns**:

- `Promise<NetworkPolicyInfo>`

***

## idempotencyKeyForName

```ts
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

```ts
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

```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\<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

```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\<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

```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`/`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

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

```ts
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

```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).