Daytona SDKs — V2 (TypeScript + Python)

The Daytona V2 client libraries and the daytona CLI. Package names are @daytona/sdk (npm) and daytona / module daytona (PyPI); the CLI lives in cli/.

The SDKs expose Daytona's API through resource handles and namespaces for processes, files, Git, code execution, ports and computer use.

Layout

.
├── cli/             daytona CLI (Go)
├── contract/        OpenAPI contracts the SDKs and CLI generate their wire types from
├── sdk-python/      daytona (module daytona) — root client + daytona.v2 (async-native, sync surface generated) + daytona.v0 (bundled at publish)
├── sdk-typescript/  @daytona/sdk            — root client + /v2 + /v0 (bundled at publish), ESM + CJS
├── upgrade/         daytona-upgrade          — 0.x → 2.x migration tool: npm (upgrade/typescript/) + PyPI (upgrade/python/) packages,
│                    one shared mapping (mapping/), the generated MIGRATION.md
├── examples/        runnable examples for both SDKs
├── e2e/             live API e2e, run.sh (needs DAYTONA_API_KEY)
├── scripts/         bundle-v0.sh            — publish-time v0 namespace bundling; its output is never committed
│                    (+ v0-sdk-version, the pinned 0.x tag the v0 namespace vendors;
│                    resolve-v0-tag.sh, bundle_v0_python.py, check-no-bundled-v0.sh, changelog/)
└── docs/            RELEASING.md, VERSIONING.md, PREPARING_YOUR_CHANGES.md, adr/ (architecture decision records)

The shared V2 model (both languages, one shape)

• Serializable handles. sandbox.to_json() / toJSON() returns a SandboxHandleJSON: a credential-free snapshot of the sandbox's metadata, the same in both SDKs. Another worker reconnects with d.v2.get(id); a process reconnects with sandbox.process.connect(...) — built for RL rollouts that fan work across workers. A reconnected code process (ProcessKind code) handle can still replay logs and wait/kill, but it does not reconstruct a decomposed InterpreterResult on another worker.
• Detached vs awaited, typed apart. start() → handle; run() → result.
• Shareable volumes. The v2 client exposes volumes.create/get/list/delete, with explicit iter() traversal for all pages. Attach volumes using the volumes create option and refresh mounted data with sandbox.volumes.pull(). The CLI exposes the volume command group and --volume on Linux and macOS sandbox creates. See the volume examples.
• Everything replayable. Cursor-paged logs(), SSE streaming with resume, wait() long-poll; nothing requires having been attached.
• Filesystem watches are SSE-backed. Both SDKs expose start-gated directory watches over GET /files/watch; TS callbacks are awaited sequentially and Python exposes a drainable event queue.
• Filesystem pre-signed transfer URLs are minted by the API. Both SDKs POST {method, path, expires_at} to /sandboxes/{id}/files/sign and compose the download/upload link from their own toolbox base plus the returned signature / expires_at. sandbox.rotate_signing_key() / sandbox.rotateSigningKey() POST /sandboxes/{id}/signing-key/rotate, receive 204 with no body and invalidate every outstanding link for the sandbox shortly after. expires_in_seconds / expiresInSeconds must be from 1 to 604800 (7 days) before any request — never-expiring links do not exist. A per-sandbox proxy override may be given either as a concrete sandbox URL or as the {sandboxId} / {sandbox_id} template — the placeholder is a path segment (https://proxy.example/sandboxes/{sandboxId}); a placeholder in the scheme, host, query or fragment is rejected, and the id is percent-encoded into it identically in both SDKs. Direct toolbox URLs are not supported here: pre-signed URLs require the sandbox's toolbox proxy URL.
• Interpreter = code executions (kind:"code"): Python and TS/JS with setup progress on the setup channel. Timeouts are CLIENT-side (on expiry the SDK interrupts the kernel like ^C). Rich results[] / logs / error decomposition comes from runCode() / interpreter.run(), not from rehydrating a serialized code-process handle elsewhere. If an explicit named context vanished, the SDK surfaces the typed SESSION_NOT_FOUND error; the caller recreates the context and chooses what to rerun.
• Sandbox service namespaces stay mirrored. Both SDKs expose ports and computer-use alongside process, fs, git, interpreter, and pty, with matching wire fields and mirrored tests.
• Network policy (Linux and macOS sandboxes) uses explicit compare-and-swap. Both SDKs expose an additive create-time network_policy / networkPolicy field and get_network_policy / update_network_policy / reset_network_policy (Python) plus getNetworkPolicy / updateNetworkPolicy / resetNetworkPolicy (TypeScript) for GET|PUT /sandboxes/{id}/network-policy. The read side carries desired vs applied policy, the quoted desired ETag, applied_start_id / applied_revision, and pending/failed metadata; writes use full replacement with caller-supplied If-Match, and reset sends a literal JSON null. The serializers preserve omitted vs null vs [] for domain lists; with domains present they omit block_all unless the caller sets it, and an explicit false is rejected locally as NETWORK_POLICY_DOMAINS_REQUIRE_BLOCK_ALL; they also keep the read-side version: 2 field out of write input. The API rejects unsupported sandbox configurations.
• Runtime-managed sandbox secret attachments use the same compare-and-swap shape. Both SDKs expose them on the sandbox handle: Python sandbox.get_secrets() / sandbox.replace_secrets(secrets=..., if_match=...), TypeScript sandbox.getSecrets() / sandbox.replaceSecrets(secrets, { ifMatch }), for GET|PUT /sandboxes/{id}/secrets. Responses carry the desired secret names, desired/applied revision state, the quoted desired ETag, the apply status (pending/applied/failed) with its error, and capture metadata; writes are full replacement only, use caller-supplied If-Match, and never send or return secret values.
• Typed errors from one catalog. Status-level bases → code-specific subclasses with code/source; each SDK's constants are drift-tested against the contract artifact contract/toolbox-openapi.json.
• Mac reservations buy physical Macs. Both SDKs reserve one Mac per reservation, individually or in bulk. Sandbox CPU, memory, and disk sizes are per-create inputs. MacModel exposes max_sandboxes and default_size.
• Signals use bare names on the surface (TERM, INT, …), SIG* on the wire.

Verification

(cd sdk-python && uv venv && uv pip install -e '.[dev]' && .venv/bin/python -m pytest -x -q)
(cd sdk-typescript && npm install && npm run typecheck && npm test && npm run build)
(cd cli && go vet ./... && go test ./...)
scripts/test-upgrade.sh   # both daytona-upgrade packages + mapping / guide drift

The TypeScript suite also runs a live toolbox test when DAYTONA_SDKTS_TOOLBOX_URL points at a reachable sandbox toolbox, and skips it otherwise. The end-to-end suites (e2e/, run with e2e/run.sh) run against a Daytona deployment when DAYTONA_API_KEY is set. Details: each package's DEVELOPMENT.md.

Releases: RELEASING.md · VERSIONING.md · CHANGELOG.md. Every PR that changes an SDK adds one changelog fragment under changelog.d/ (not a line in CHANGELOG.md); see changelog.d/README.md.

License

The SDKs are licensed under Apache-2.0; the CLI (cli/) under AGPL-3.0. See COPYRIGHT and CONTRIBUTING.md.