Python SDK Reference
The Daytona Python SDK provides a robust interface for programmatically interacting with Daytona Sandboxes.
Installation
Section titled “Installation”This reference documents the Daytona v0 API, which Python SDK 2.x exposes as the v0 namespace (Daytona().v0). The module pages show the 0.x SDK’s examples; see Reference for how they map to SDK 2.x. Install SDK 2.x with the v0-sdk extra using pip:
pip install "daytona[v0-sdk]>=2,<3"Or using poetry:
poetry add "daytona[v0-sdk]>=2,<3"SDK 2.x connects to Daytona Cloud. To use a custom API URL, stay on SDK 0.x (pip install "daytona<1") and call the client methods on 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.
from daytona import Daytona
def main(): # Initialize the SDK (uses environment variables by default) daytona = Daytona()
# Create a new sandbox sandbox = daytona.v0.create()
# Execute a command response = sandbox.process.exec("echo 'Hello, World!'") print(response.result)
if __name__ == "__main__": main()import asynciofrom daytona import AsyncDaytona
async def main(): # Initialize the SDK (uses environment variables by default) async with AsyncDaytona() as daytona: # Create a new sandbox sandbox = await daytona.v0.create()
# Execute a command response = await sandbox.process.exec("echo 'Hello, World!'") print(response.result)
if __name__ == "__main__": asyncio.run(main())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:
from daytona import Daytona, DaytonaConfigfrom daytona.v0 import CreateSandboxFromSnapshotParams
# Using environment variables (DAYTONA_API_KEY, DAYTONA_TARGET)daytona = Daytona()
# Using explicit configurationconfig = DaytonaConfig(api_key="YOUR_API_KEY")daytona = Daytona(config)
# Creating a sandbox in a specific regionsandbox = daytona.v0.create(CreateSandboxFromSnapshotParams(target="us"))import asynciofrom daytona import AsyncDaytona, DaytonaConfigfrom daytona.v0 import CreateSandboxFromSnapshotParams
async def main(): # Using environment variables (DAYTONA_API_KEY, DAYTONA_TARGET) async with AsyncDaytona() as daytona: # Your async code here pass
# Using explicit configuration config = DaytonaConfig(api_key="YOUR_API_KEY") async with AsyncDaytona(config) as daytona: # Creating a sandbox in a specific region sandbox = await daytona.v0.create(CreateSandboxFromSnapshotParams(target="us"))
if __name__ == "__main__": asyncio.run(main())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 Daytona().v0 or AsyncDaytona().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.
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 raises an error, so no 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=trueAsync Python SDK
Section titled “Async Python SDK”Daytona provides an additional DAYTONA_HAPPY_EYEBALLS_DELAY environment variable for HTTP transport tuning in the async Python SDK. Use it to reduce intermittent async connection failures, such as aiohttp.ClientConnectorError, that can occur on dual-stack (IPv4/IPv6) networks.
| Variable | Description | Required |
|---|---|---|
DAYTONA_HAPPY_EYEBALLS_DELAY | Controls aiohttp Happy Eyeballs (IPv4/IPv6 connection race) delay in seconds. | No |
- unset or empty: use
aiohttpdefault behavior none(case-insensitive): disable the IPv4/IPv6 race- non-negative float (for example
0.25): set an explicit delay in seconds
# Disable Happy Eyeballsexport DAYTONA_HAPPY_EYEBALLS_DELAY=none
# Or set an explicit delay in secondsexport DAYTONA_HAPPY_EYEBALLS_DELAY=0.25Reference
Section titled “Reference”The Python SDK reference documents the following modules:
- CodeInterpreter
- ComputerUse
- Daytona
- FileSystem
- Git
- LspServer
- ObjectStorage
- Process
- Sandbox
- Secret
- Snapshot
- Volume
- AsyncCodeInterpreter
- AsyncComputerUse
- AsyncDaytona
- AsyncFileSystem
- AsyncGit
- AsyncLspServer
- AsyncObjectStorage
- AsyncProcess
- AsyncSandbox
- AsyncSecret
- AsyncSnapshot
- AsyncVolume