Daytona

class Daytona()

Main class for interacting with the Daytona API.

This class provides methods to create, manage, and interact with Daytona Sandboxes. It can be initialized either with explicit configuration or using environment variables.

Attributes:

volume VolumeService - Service for managing volumes.
snapshot SnapshotService - Service for managing snapshots.

Example:

Using environment variables:

daytona = Daytona()  # Uses DAYTONA_API_KEY, DAYTONA_API_URL
sandbox = daytona.create()

Using explicit configuration:

config = DaytonaConfig(
    api_key="your-api-key",
    api_url="https://your-api.com",
    target="us"
)
daytona = Daytona(config)
sandbox = daytona.create()

Using OpenTelemetry tracing:

config = DaytonaConfig(
    api_key="your-api-key",
    experimental={"otelEnabled": True}  # Enable OpenTelemetry tracing through experimental config
)
async with Daytona(config) as daytona:
    sandbox = daytona.create()
    # All SDK operations will be traced
# OpenTelemetry traces are flushed on close

Daytona.init

def __init__(config: DaytonaConfig | None = None)

Initializes Daytona instance with optional configuration.

If no config is provided, reads from environment variables:

DAYTONA_API_KEY: Required API key for authentication
DAYTONA_API_URL: Required api URL
DAYTONA_TARGET: Optional target environment (if not provided, default region for the organization is used)

Arguments:

config DaytonaConfig | None - Object containing api_key, api_url, and target.

Raises:

DaytonaError - If API key is not provided either through config or environment variables

Example:

from daytona import Daytona, DaytonaConfig
# Using environment variables
daytona1 = Daytona()

# Using explicit configuration
config = DaytonaConfig(
    api_key="your-api-key",
    api_url="https://your-api.com",
    target="us"
)
daytona2 = Daytona(config)

Daytona.create

@overload
def create(params: CreateSandboxFromSnapshotParams | None = None,
           *,
           timeout: float = 60) -> Sandbox

Creates Sandboxes from specified or default snapshot. You can specify various parameters, including language, image, environment variables, and volumes.

Arguments:

params CreateSandboxFromSnapshotParams | None - Parameters for Sandbox creation. If not provided, defaults to default Daytona snapshot and Python language.
timeout float - Timeout (in seconds) for sandbox creation. 0 means no timeout. Default is 60 seconds.

Returns:

Sandbox - The created Sandbox instance.

Raises:

DaytonaError - If timeout, auto_stop_interval or auto_archive_interval is negative; If sandbox fails to start or times out

Example:

Create a default Python Sandbox:

sandbox = daytona.create()

Create a custom Sandbox:

params = CreateSandboxFromSnapshotParams(
    language="python",
    snapshot="my-snapshot-id",
    env_vars={"DEBUG": "true"},
    auto_stop_interval=0,
    auto_archive_interval=60,
    auto_delete_interval=120
)
sandbox = daytona.create(params, timeout=40)

Daytona.create

@overload
def create(
        params: CreateSandboxFromImageParams | None = None,
        *,
        timeout: float = 60,
        on_snapshot_create_logs: Callable[[str], None] | None = None
) -> Sandbox

Creates Sandboxes from specified image available on some registry or declarative Daytona Image. You can specify various parameters, including resources, language, image, environment variables, and volumes. Daytona creates snapshot from provided image and uses it to create Sandbox.

Arguments:

params CreateSandboxFromImageParams | None - Parameters for Sandbox creation from image.
timeout float - Timeout (in seconds) for sandbox creation. 0 means no timeout. Default is 60 seconds.
on_snapshot_create_logs Callable[[str], None] | None - This callback function handles snapshot creation logs.

Returns:

Sandbox - The created Sandbox instance.

Raises:

DaytonaError - If timeout, auto_stop_interval or auto_archive_interval is negative; If sandbox fails to start or times out

Example:

Create a default Python Sandbox from image:

sandbox = daytona.create(CreateSandboxFromImageParams(image="debian:12.9"))

Create a custom Sandbox from declarative Image definition:

declarative_image = (
    Image.base("alpine:3.18")
    .pipInstall(["numpy", "pandas"])
    .env({"MY_ENV_VAR": "My Environment Variable"})
)
params = CreateSandboxFromImageParams(
    language="python",
    image=declarative_image,
    env_vars={"DEBUG": "true"},
    resources=Resources(cpu=2, memory=4),
    auto_stop_interval=0,
    auto_archive_interval=60,
    auto_delete_interval=120
)
sandbox = daytona.create(
    params,
    timeout=40,
    on_snapshot_create_logs=lambda chunk: print(chunk, end=""),
)

Daytona.delete

@with_instrumentation()
def delete(sandbox: Sandbox, timeout: float = 60) -> None

Deletes a Sandbox.

Arguments:

sandbox Sandbox - The Sandbox instance to delete.
timeout float - Timeout (in seconds) for sandbox deletion. 0 means no timeout. Default is 60 seconds.

Raises:

DaytonaError - If sandbox fails to delete or times out

Example:

sandbox = daytona.create()
# ... use sandbox ...
daytona.delete(sandbox)  # Clean up when done

Daytona.get

@intercept_errors(message_prefix="Failed to get sandbox: ")
@with_instrumentation()
def get(sandbox_id_or_name: str) -> Sandbox

Gets a Sandbox by its ID or name.

Arguments:

sandbox_id_or_name str - The ID or name of the Sandbox to retrieve.

Returns:

Sandbox - The Sandbox instance.

Raises:

DaytonaError - If sandbox_id_or_name is not provided.

Example:

sandbox = daytona.get("my-sandbox-id-or-name")
print(sandbox.state)

Daytona.find_one

@intercept_errors(message_prefix="Failed to find sandbox: ")
@with_instrumentation()
def find_one(sandbox_id_or_name: str | None = None,
             labels: dict[str, str] | None = None) -> Sandbox

Finds a Sandbox by its ID or name or labels.

Arguments:

sandbox_id_or_name str | None - The ID or name of the Sandbox to retrieve.
labels dict[str, str] | None - Labels to filter Sandboxes.

Returns:

Sandbox - First Sandbox that matches the ID or name or labels.

Raises:

DaytonaError - If no Sandbox is found.

Example:

sandbox = daytona.find_one(labels={"my-label": "my-value"})
print(f"Sandbox ID: {sandbox.id} State: {sandbox.state}")

Daytona.list

@intercept_errors(message_prefix="Failed to list sandboxes: ")
@with_instrumentation()
def list(labels: dict[str, str] | None = None,
         page: int | None = None,
         limit: int | None = None) -> PaginatedSandboxes

Returns paginated list of Sandboxes filtered by labels.

Arguments:

labels dict[str, str] | None - Labels to filter Sandboxes.
page int | None - Page number for pagination (starting from 1).
limit int | None - Maximum number of items per page.

Returns:

PaginatedSandboxes - Paginated list of Sandbox instances that match the labels.

Example:

result = daytona.list(labels={"my-label": "my-value"}, page=2, limit=10)
for sandbox in result.items:
    print(f"{sandbox.id}: {sandbox.state}")

Daytona.start

@with_instrumentation()
def start(sandbox: Sandbox, timeout: float = 60) -> None

Starts a Sandbox and waits for it to be ready.

Arguments:

sandbox Sandbox - The Sandbox to start.
timeout float - Optional timeout in seconds to wait for the Sandbox to start. 0 means no timeout. Default is 60 seconds.

Raises:

DaytonaError - If timeout is negative; If Sandbox fails to start or times out

Daytona.stop

@with_instrumentation()
def stop(sandbox: Sandbox, timeout: float = 60) -> None

Stops a Sandbox and waits for it to be stopped.

Arguments:

sandbox Sandbox - The sandbox to stop
timeout float - Optional timeout (in seconds) for sandbox stop. 0 means no timeout. Default is 60 seconds.

Raises:

DaytonaError - If timeout is negative; If Sandbox fails to stop or times out

CodeLanguage

class CodeLanguage(str, Enum)

Programming languages supported by Daytona

Enum Members:

PYTHON (“python”)
TYPESCRIPT (“typescript”)
JAVASCRIPT (“javascript”)

DaytonaConfig

class DaytonaConfig(BaseModel)

Configuration options for initializing the Daytona client.

Attributes:

api_key str | None - API key for authentication with the Daytona API. If not set, it must be provided via the environment variable DAYTONA_API_KEY, or a JWT token must be provided instead.
jwt_token str | None - JWT token for authentication with the Daytona API. If not set, it must be provided via the environment variable DAYTONA_JWT_TOKEN, or an API key must be provided instead.
organization_id str | None - Organization ID used for JWT-based authentication. Required if a JWT token is provided, and must be set either here or in the environment variable DAYTONA_ORGANIZATION_ID.
api_url str | None - URL of the Daytona API. Defaults to 'https://app.daytona.io/api' if not set here or in the environment variable DAYTONA_API_URL.
server_url str | None - Deprecated. Use api_url instead. This property will be removed in a future version.
target str | None - Target runner location for the Sandbox. Default region for the organization is used if not set here or in the environment variable DAYTONA_TARGET.
_experimental dict[str, any] | None - Configuration for experimental features.

Example:

config = DaytonaConfig(api_key="your-api-key")

config = DaytonaConfig(jwt_token="your-jwt-token", organization_id="your-organization-id")

CreateSandboxBaseParams

class CreateSandboxBaseParams(BaseModel)

Base parameters for creating a new Sandbox.

Attributes:

name str | None - Name of the Sandbox.
language CodeLanguage | CodeLanguageLiteral | None - Programming language for the Sandbox. Defaults to “python”.
os_user str | None - OS user for the Sandbox.
env_vars dict[str, str] | None - Environment variables to set in the Sandbox.
labels dict[str, str] | None - Custom labels for the Sandbox.
public bool | None - Whether the Sandbox should be public.
timeout float | None - Timeout in seconds for Sandbox to be created and started.
auto_stop_interval int | None - Interval in minutes after which Sandbox will automatically stop if no Sandbox event occurs during that time. Default is 15 minutes. 0 means no auto-stop.
auto_archive_interval int | None - Interval in minutes after which a continuously stopped Sandbox will automatically archive. Default is 7 days. 0 means the maximum interval will be used.
auto_delete_interval int | None - Interval in minutes after which a continuously stopped Sandbox will automatically be deleted. By default, auto-delete is disabled. Negative value means disabled, 0 means delete immediately upon stopping.
volumes list[VolumeMount] | None - List of volumes mounts to attach to the Sandbox.
network_block_all bool | None - Whether to block all network access for the Sandbox.
network_allow_list str | None - Comma-separated list of allowed CIDR network addresses for the Sandbox.
ephemeral bool | None - Whether the Sandbox should be ephemeral. If True, auto_delete_interval will be set to 0.

CreateSandboxFromImageParams

class CreateSandboxFromImageParams(CreateSandboxBaseParams)

Parameters for creating a new Sandbox from an image.

Attributes:

image str | Image - Custom Docker image to use for the Sandbox. If an Image object is provided, the image will be dynamically built.
resources Resources | None - Resource configuration for the Sandbox. If not provided, sandbox will have default resources.

CreateSandboxFromSnapshotParams

class CreateSandboxFromSnapshotParams(CreateSandboxBaseParams)

Parameters for creating a new Sandbox from a snapshot.

Attributes:

snapshot str | None - Name of the snapshot to use for the Sandbox.

Daytona

Daytona.__init__

Daytona.create

Daytona.create

Daytona.delete

Daytona.get

Daytona.find_one

Daytona.list

Daytona.start

Daytona.stop

CodeLanguage

DaytonaConfig

CreateSandboxBaseParams

CreateSandboxFromImageParams

CreateSandboxFromSnapshotParams

Daytona.init