TypeScript SDK Reference
The Daytona TypeScript SDK provides a powerful interface for programmatically interacting with Daytona Sandboxes.
Installation
Section titled “Installation”This reference documents the Daytona v0 API, which TypeScript SDK 2.x exposes as the v0 namespace (new Daytona().v0). The module pages show the 0.x SDK’s examples; see Reference for how they map to SDK 2.x. The package includes the namespace, so no extra install is required. SDK 2.x requires Node.js 22.15 or later.
Install the Daytona TypeScript SDK using npm:
npm install @daytona/sdk@2Or using yarn:
yarn add @daytona/sdk@2SDK 2.x connects to Daytona Cloud. To use a custom API URL, stay on SDK 0.x (npm install @daytona/sdk@0) and call the client methods on new Daytona() directly. For the changes between the versions, see Upgrade to v2.
Getting Started
Section titled “Getting Started”Create a Sandbox
Section titled “Create a Sandbox”Create a Daytona Sandbox to run your code securely in an isolated environment. The following snippet is an example “Hello World” program that runs securely inside a Daytona Sandbox.
import { Daytona } from '@daytona/sdk'
async function main() { // Initialize the SDK (uses environment variables by default) const daytona = new Daytona()
// Create a new sandbox const sandbox = await daytona.v0.create({ language: 'typescript', envVars: { NODE_ENV: 'development' }, })
// Execute a command const response = await sandbox.process.executeCommand('echo "Hello, World!"') console.log(response.result)}
main().catch(console.error)Configuration
Section titled “Configuration”The Daytona SDK can be configured using environment variables or by passing options to the constructor. The v0 namespace reads DAYTONA_API_KEY and DAYTONA_TARGET from the environment. To create a sandbox in a specific region, pass target to the create call:
import { Daytona } from '@daytona/sdk'
// Using environment variables (DAYTONA_API_KEY, DAYTONA_TARGET)const daytona = new Daytona()
// Using explicit configurationconst configured = new Daytona({ apiKey: 'YOUR_API_KEY' })
// Creating a sandbox in a specific regionconst sandbox = await configured.v0.create({ target: 'us' })For more information on configuring the Daytona SDK, see API keys.
Real-time state updates
Section titled “Real-time state updates”The v0 namespace streams sandbox state changes over a WebSocket (Socket.IO) connection by default. Sandbox lifecycle operations that wait on a state change (start, stop, pause, resize, snapshot, delete with wait) complete as soon as the server pushes the new state, instead of waiting for the next polling interval.
Each new Daytona().v0 client opens a single WebSocket connection shared by all of its sandboxes. A sparse polling safety net runs alongside the event stream, so a missed event never hangs a waiting operation. Note: The connection never keeps Node.js or Bun processes alive.
The WebSocket handshake carries source and sdkVersion query parameters, equivalent to the X-Daytona-Source and X-Daytona-SDK-Version REST headers. The SDK collects no client-side telemetry.
Polling fallback
Section titled “Polling fallback”If the WebSocket connection cannot be established, for example when a proxy, firewall, or network policy blocks it, the SDK falls back to polling automatically. Connection setup runs in the background and never throws, so no error handling is required.
Opt out of event streaming
Section titled “Opt out of event streaming”In polling-only mode the SDK never opens a WebSocket connection. Sandbox state is observed exclusively by polling the REST API, with the same cadence as SDK versions before event streaming.
To opt out, set the DAYTONA_USE_DEPRECATED_POLLING environment variable:
export DAYTONA_USE_DEPRECATED_POLLING=trueMultiple runtime support
Section titled “Multiple runtime support”The TypeScript SDK ships as a dual ESM/CJS package for Node.js 22.15 or later and for browser environments with WebSocket. Import the v0 resource types, such as Image, from @daytona/sdk/v0; the client comes from @daytona/sdk.
A browser bundle of the root client includes the v0 SDK, so daytona.v0 works in browsers too. For browser apps with Vite (or any browser bundler), install vite-plugin-node-polyfills and add it to your vite.config.ts:
import { defineConfig } from 'vite'import { nodePolyfills } from 'vite-plugin-node-polyfills'
export default defineConfig({ plugins: [nodePolyfills({ globals: { Buffer: true, process: true, global: true } })],})The SDK uses Node’s Buffer for binary data (downloaded files, multipart bodies). Browsers don’t ship Buffer, so the polyfill provides it. Without it, basic operations like Image.base() and daytona.v0.list() still work, but methods that handle binary payloads (fs.downloadFile, fs.downloadFiles) will throw.
Some runtimes don’t expose the full set of Node.js APIs (browsers and edge runtimes have no filesystem, no crypto, etc.). Methods that depend on those APIs throw a clear runtime error instead of silently producing wrong results.
Reference
Section titled “Reference”The TypeScript SDK reference documents the following modules: