# zidane/contexts/daytona

> A sandbox provider backed by Daytona.

Import: `import { … } from 'zidane/contexts/daytona'`. Source: [src/contexts/daytona.ts](https://github.com/Tahul/zidane/blob/main/src/contexts/daytona.ts).

Use `createDaytonaProvider` for a remote sandbox on Daytona. It returns a `SandboxProvider` that you wrap with `createSandboxContext`, needs the optional `@daytona/sdk` package, and reads `DAYTONA_API_KEY` when you pass no key. The other exports convert Daytona responses, build create parameters, wait for a new sandbox to answer and run the setup script before the first turn. See [Execution contexts](https://zidane.si/docs/execution-contexts.md).

```ts
import { createSandboxContext } from 'zidane/contexts/sandbox'
import { createDaytonaProvider } from 'zidane/contexts/daytona'

const context = createSandboxContext(createDaytonaProvider({ cwd: '/home/daytona/project' }))
const handle = await context.spawn()
const result = await context.exec(handle, 'ls')
console.log(result.stdout)
await context.destroy(handle)
```

## Functions

### `createDaytonaProvider`

Function.

Builds a [`SandboxProvider`](https://zidane.si/docs/reference/contexts-sandbox.md#SandboxProvider) backed by Daytona. Requires the optional peer dependency `@daytona/sdk`.

```ts
function createDaytonaProvider(options?: DaytonaProviderOptions): SandboxProvider
```

**Parameters**

- `options?` (`DaytonaProviderOptions`, default `{}`): API key, URL, target, snapshot, resources, environment and lifecycle settings.

**Returns** `SandboxProvider`

**Example**

```ts
import { createDaytonaProvider } from 'zidane/contexts/daytona'
import { createSandboxContext } from 'zidane/contexts/sandbox'

const execution = createSandboxContext(
  createDaytonaProvider({ apiKey: process.env.DAYTONA_API_KEY, onDestroy: 'stop' }),
)
```

Source: [src/contexts/daytona.ts:289](https://github.com/Tahul/zidane/blob/main/src/contexts/daytona.ts#L289)

### `normalizeDaytonaExecResult`

Function.

Converts a Daytona execute response to an [`ExecResult`](https://zidane.si/docs/reference/contexts.md#ExecResult). Falls back across the response fields for stdout and defaults the exit code to `0`.

```ts
function normalizeDaytonaExecResult(response: DaytonaExecuteResponse): ExecResult
```

**Parameters**

- `response` (`DaytonaExecuteResponse`): Response of the Daytona process execute call.

**Returns** `ExecResult`

Source: [src/contexts/daytona-sdk.ts:143](https://github.com/Tahul/zidane/blob/main/src/contexts/daytona-sdk.ts#L143)

### `resolveDaytonaCreateParams`

Function.

Builds the parameters for creating a Daytona sandbox. Per-spawn `sandboxConfig` values win over the provider options, connection keys are dropped, and environment variables are merged. Returns `undefined` when nothing is set.

```ts
function resolveDaytonaCreateParams(
  sandboxConfig: Record<string, unknown>,
  options: DaytonaProviderOptions,
  envVars: Record<string, string> | undefined,
): DaytonaCreateParams | undefined
```

**Parameters**

- `sandboxConfig` (`Record<string, unknown>`): Per-spawn `SpawnConfig.sandbox` values.
- `options` (`DaytonaProviderOptions`): Provider options that supply defaults.
- `envVars` (`Record<string, string> | undefined`): Provider-level environment variables.

**Returns** `DaytonaCreateParams | undefined`

Source: [src/contexts/daytona.ts:163](https://github.com/Tahul/zidane/blob/main/src/contexts/daytona.ts#L163)

### `resolveDaytonaEnv`

Function.

Merges the provider-level environment with the per-spawn environment, per-spawn winning on key conflicts. Returns `undefined` when the result is empty.

```ts
function resolveDaytonaEnv(
  optionEnv: Record<string, string> | undefined,
  perSpawnEnv: Record<string, string> | undefined,
): Record<string, string> | undefined
```

**Parameters**

- `optionEnv` (`Record<string, string> | undefined`): Environment from the provider options.
- `perSpawnEnv` (`Record<string, string> | undefined`): Environment from the spawn config.

**Returns** `Record<string, string> | undefined`

Source: [src/contexts/daytona-sdk.ts:130](https://github.com/Tahul/zidane/blob/main/src/contexts/daytona-sdk.ts#L130)

### `runDaytonaPregame`

Function.

Uploads a setup script to `/tmp` and runs it in the sandbox. Throws on a non-zero exit so the caller can tear the sandbox down.

```ts
function runDaytonaPregame(
  sandbox: DaytonaSandbox,
  logger: Logger,
  opts: { content: string; cwd?: string; envVars?: Record<string, string>; name: string },
): Promise<void>
```

**Parameters**

- `sandbox` (`DaytonaSandbox`): Sandbox to run the script in.
- `logger` (`Logger`): Logger for progress and failure lines.
- `opts` (`{ content: string; cwd?: string; envVars?: Record<string, string>; name: string }`): Script `name`, `content`, and optional `cwd` and `envVars` for the run.

**Returns** `Promise<void>`

Source: [src/contexts/daytona.ts:242](https://github.com/Tahul/zidane/blob/main/src/contexts/daytona.ts#L242)

### `waitForDaytonaReady`

Function.

Waits until a Daytona sandbox runs commands. Polls a trivial command and throws when the deadline passes, after running `cleanupOnTimeout`.

```ts
function waitForDaytonaReady(
  sandbox: DaytonaSandbox,
  logger: Logger,
  opts: DaytonaReadinessOptions,
): Promise<void>
```

**Parameters**

- `sandbox` (`DaytonaSandbox`): Sandbox to probe.
- `logger` (`Logger`): Logger for progress lines.
- `opts` (`DaytonaReadinessOptions`): Deadline and probe settings.

**Returns** `Promise<void>`

Source: [src/contexts/daytona.ts:204](https://github.com/Tahul/zidane/blob/main/src/contexts/daytona.ts#L204)

## Interfaces

### `DaytonaProviderOptions`

Interface.

Options for [`createDaytonaProvider`](https://zidane.si/docs/reference/contexts-daytona.md#createDaytonaProvider).

```ts
interface DaytonaProviderOptions
```

**Properties**

- `apiKey?` (`string`): Daytona API key. Falls back to the `DAYTONA_API_KEY` env var when omitted.
- `apiUrl?` (`string`): Daytona API URL. Falls back to `DAYTONA_API_URL`, then Daytona's hosted default.
- `cwd?` (`string`): Default working directory, applied when a spawn doesn't set `SpawnConfig.cwd`.
- `env?` (`Record<string, string>`): Environment variables baked into the sandbox and re-sent on every command.
- `image?` (`unknown`): Daytona image/declarative builder input used when creating a fresh sandbox.
- `language?` (`string`): Runtime used for Daytona's code tooling. Shell execution works either way.
- `logger?` (`Logger`): Logger for provider-level lifecycle lines.
- `onDestroy?` (`DaytonaOnDestroy`): What to do with an owned sandbox on destroy:

  - `'delete'` / `'kill'` (default) — call `sandbox.delete()`.
  - `'stop'` / `'pause'` — call `sandbox.stop()` so Daytona preserves state
    according to the runner's stop semantics.
  - `'archive'` — stop, then archive for longer-term persistence.
  - `'leave'` — make no API call.
- `ownAttached?` (`boolean`): Take ownership of an attached (`sandboxId`) sandbox's lifecycle, so
  `destroy()` applies `onDestroy` to it (stop / archive / delete)
  instead of leaving it running.

  The intended caller is a durable host that *owns* the sandbox across
  invocations: mint it once, journal its id, re-attach via `sandboxId` on
  every replay/resume, and clean it up at the end of the logical run. Without
  this an attached sandbox can never be stopped/deleted through the provider —
  a leak for host-owned sandboxes. No effect when creating a fresh sandbox
  (those are always owned). Spawn-time failures (readiness timeout, pregame
  error) still never delete a pre-existing attached sandbox — only sandboxes
  this provider *created* are auto-cleaned on spawn failure.

  Default: `false`.
- `pregame?` (`{ content: string; name: string }`): Setup script to upload and run once the sandbox is ready.
- `readinessTimeoutSeconds?` (`number`): Total deadline, in seconds, for the post-create readiness probe. Defaults to `60`.
- `resources?` (`DaytonaResources`): Daytona sandbox resources.
- `sandboxId?` (`string`): Attach to a pre-existing sandbox by id or name instead of creating a fresh
  one. By default the provider treats attached sandboxes as externally owned
  and leaves them running on destroy/failure (set `ownAttached` to take
  over the lifecycle).
- `snapshot?` (`string`): Daytona snapshot used when creating a fresh sandbox. An attached sandbox built from a different snapshot is deleted and recreated from this one.
- `target?` (`string`): Daytona target / region. Falls back to `DAYTONA_TARGET`, then the org default.

Source: [src/contexts/daytona.ts:39](https://github.com/Tahul/zidane/blob/main/src/contexts/daytona.ts#L39)

### `DaytonaReadinessOptions`

Interface.

Options for [`waitForDaytonaReady`](https://zidane.si/docs/reference/contexts-daytona.md#waitForDaytonaReady).

```ts
interface DaytonaReadinessOptions
```

**Properties**

- `cleanupOnTimeout?` (`() => Promise<void>`): Optional cleanup for owned sandboxes that never become ready.
- `now?` (`() => number`): Clock source — injectable for deterministic tests.
- `sleep?` (`(ms: number) => Promise<void>`): Sleep between probes — injectable for deterministic tests.
- `timeoutSeconds` (`number`): Total deadline in seconds. `<= 0` disables the probe entirely.

Source: [src/contexts/daytona.ts:108](https://github.com/Tahul/zidane/blob/main/src/contexts/daytona.ts#L108)

## Types

### `DaytonaOnDestroy`

Type.

What to do with an owned Daytona sandbox on destroy: `delete`, `kill`, `stop`, `pause`, `archive` or `leave`. See `DaytonaProviderOptions.onDestroy`.

```ts
type DaytonaOnDestroy = 'delete' | 'kill' | 'stop' | 'pause' | 'archive' | 'leave'
```

Source: [src/contexts/daytona.ts:36](https://github.com/Tahul/zidane/blob/main/src/contexts/daytona.ts#L36)