zidanezidane/
A sandbox provider backed by Daytona.
import { … } from 'zidane/contexts/daytona'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.
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#
createDaytonaProviderFunction#
Builds a SandboxProvider backed by Daytona. Requires the optional peer dependency @daytona/sdk.
function createDaytonaProvider(options?: DaytonaProviderOptions): SandboxProviderParameters
| Name | Type | Default | Description |
|---|---|---|---|
| options? | DaytonaProviderOptions | {} | API key, URL, target, snapshot, resources, environment and lifecycle settings. |
Returns
Example
import { createDaytonaProvider } from 'zidane/contexts/daytona'
import { createSandboxContext } from 'zidane/contexts/sandbox'
const execution = createSandboxContext(
createDaytonaProvider({ apiKey: process.env.DAYTONA_API_KEY, onDestroy: 'stop' }),
)normalizeDaytonaExecResultFunction#
Converts a Daytona execute response to an ExecResult. Falls back across the response fields for stdout and defaults the exit code to 0.
function normalizeDaytonaExecResult(response: DaytonaExecuteResponse): ExecResultParameters
| Name | Type | Description |
|---|---|---|
| response | DaytonaExecuteResponse | Response of the Daytona process execute call. |
Returns
resolveDaytonaCreateParamsFunction#
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.
function resolveDaytonaCreateParams(
sandboxConfig: Record<string, unknown>,
options: DaytonaProviderOptions,
envVars: Record<string, string> | undefined,
): DaytonaCreateParams | undefinedParameters
| Name | Type | Description |
|---|---|---|
| sandboxConfig | Record<string, unknown> | Per-spawn |
| options | DaytonaProviderOptions | Provider options that supply defaults. |
| envVars | Record<string, string> | undefined | Provider-level environment variables. |
Returns
DaytonaCreateParams | undefinedresolveDaytonaEnvFunction#
Merges the provider-level environment with the per-spawn environment, per-spawn winning on key conflicts. Returns undefined when the result is empty.
function resolveDaytonaEnv(
optionEnv: Record<string, string> | undefined,
perSpawnEnv: Record<string, string> | undefined,
): Record<string, string> | undefinedParameters
| Name | Type | Description |
|---|---|---|
| optionEnv | Record<string, string> | undefined | Environment from the provider options. |
| perSpawnEnv | Record<string, string> | undefined | Environment from the spawn config. |
Returns
Record<string, string> | undefinedrunDaytonaPregameFunction#
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.
function runDaytonaPregame(
sandbox: DaytonaSandbox,
logger: Logger,
opts: { content: string; cwd?: string; envVars?: Record<string, string>; name: string },
): Promise<void>Parameters
| Name | Type | Description |
|---|---|---|
| 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 |
Returns
Promise<void>waitForDaytonaReadyFunction#
Waits until a Daytona sandbox runs commands. Polls a trivial command and throws when the deadline passes, after running cleanupOnTimeout.
function waitForDaytonaReady(
sandbox: DaytonaSandbox,
logger: Logger,
opts: DaytonaReadinessOptions,
): Promise<void>Parameters
| Name | Type | Description |
|---|---|---|
| sandbox | DaytonaSandbox | Sandbox to probe. |
| logger | Logger | Logger for progress lines. |
| opts | DaytonaReadinessOptions | Deadline and probe settings. |
Returns
Promise<void>Interfaces#
DaytonaProviderOptionsInterface#
Options for createDaytonaProvider.
interface DaytonaProviderOptionsProperties
| Name | Type | Description |
|---|---|---|
| apiKey? | string | Daytona API key. Falls back to the |
| apiUrl? | string | Daytona API URL. Falls back to |
| cwd? | string | Default working directory, applied when a spawn doesn't set |
| 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:
|
| ownAttached? | boolean | Take ownership of an attached ( The intended caller is a durable host that owns the sandbox across
invocations: mint it once, journal its id, re-attach via Default: |
| 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 |
| 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 |
| 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 |
DaytonaReadinessOptionsInterface#
Options for waitForDaytonaReady.
interface DaytonaReadinessOptionsProperties
| Name | Type | Description |
|---|---|---|
| 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. |
Types#
DaytonaOnDestroyType#
What to do with an owned Daytona sandbox on destroy: delete, kill, stop, pause, archive or leave. See DaytonaProviderOptions.onDestroy.
type DaytonaOnDestroy = 'delete' | 'kill' | 'stop' | 'pause' | 'archive' | 'leave'