There's a lot of open issues
Daytona Toolbox API Client
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Development

~> 3.6, >= 3.6.0

Runtime

~> 1.0, >= 1.0.1
 Project Readme

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.