Sandbox Management

Sandboxes are isolated development environments managed by Daytona. This guide covers how to create, manage, and remove Sandboxes using the SDK.

Examples:

Basic usage with environment variables:

from daytona_sdk import Daytona
# Initialize using environment variables
daytona = Daytona()  # Uses env vars DAYTONA_API_KEY, DAYTONA_SERVER_URL, DAYTONA_TARGET

# Create a default Python sandbox with custom environment variables
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    env_vars={"PYTHON_ENV": "development"}
))

# Execute commands in the sandbox
response = sandbox.process.execute_command('echo "Hello, World!"')
print(response.result)

# Run Python code securely inside the sandbox
response = sandbox.process.code_run('print("Hello from Python!")')
print(response.result)

# Remove the sandbox after use
daytona.remove(sandbox)

Usage with explicit configuration:

from daytona_sdk import Daytona, DaytonaConfig, CreateSandboxParams, SandboxResources

# Initialize with explicit configuration
config = DaytonaConfig(
    api_key="your-api-key",
    server_url="https://your-server.com",
    target="us"
)
daytona = Daytona(config)

# Create a custom sandbox with specific resources and settings
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    image="python:3.11",
    resources=SandboxResources(
        cpu=2,
        memory=4,  # 4GB RAM
        disk=20    # 20GB disk
    ),
    env_vars={"PYTHON_ENV": "development"},
    auto_stop_interval=60  # Auto-stop after 1 hour of inactivity
))

# Use sandbox features
sandbox.git.clone("https://github.com/user/repo.git")
sandbox.process.execute_command("python -m pytest")

Daytona

class Daytona()

Main class for interacting with Daytona Server 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:

api_key str - API key for authentication.
server_url str - URL of the Daytona server.
target str - Default target location for Sandboxes.

Example:

Using environment variables:

daytona = Daytona()  # Uses DAYTONA_API_KEY, DAYTONA_SERVER_URL

Using explicit configuration:

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

Daytona.init

def __init__(config: Optional[DaytonaConfig] = 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_SERVER_URL: Required server URL
DAYTONA_TARGET: Optional target environment (defaults to SandboxTargetRegion.US)

Arguments:

config Optional[DaytonaConfig] - Object containing api_key, server_url, and target.

Raises:

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

Example:

from daytona_sdk import Daytona, DaytonaConfig
# Using environment variables
daytona1 = Daytona()
# Using explicit configuration
config = DaytonaConfig(
    api_key="your-api-key",
    server_url="https://your-server.com",
    target="us"
)
daytona2 = Daytona(config)

Daytona.create

@intercept_errors(message_prefix="Failed to create sandbox: ")
def create(params: Optional[CreateSandboxParams] = None,
           timeout: Optional[float] = 60) -> Sandbox

Creates Sandboxes with default or custom configurations. You can specify various parameters, including language, image, resources, environment variables, and volumes for the Sandbox.

Arguments:

params Optional[CreateSandboxParams] - Parameters for Sandbox creation. If not provided, defaults to Python language.
timeout Optional[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 or auto_stop_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 = CreateSandboxParams(
    language="python",
    name="my-sandbox",
    image="debian:12.9",
    env_vars={"DEBUG": "true"},
    resources=SandboxResources(cpu=2, memory=4096),
    auto_stop_interval=0
)
sandbox = daytona.create(params, 40)

Daytona.remove

@intercept_errors(message_prefix="Failed to remove sandbox: ")
def remove(sandbox: Sandbox, timeout: Optional[float] = 60) -> None

Removes a Sandbox.

Arguments:

sandbox Sandbox - The Sandbox instance to remove.
timeout Optional[float] - Timeout (in seconds) for sandbox removal. 0 means no timeout. Default is 60 seconds.

Raises:

DaytonaError - If sandbox fails to remove or times out

Example:

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

Daytona.get_current_workspace

@deprecated(reason=(
    "Method is deprecated. Use `get_current_sandbox` instead. This method will be removed in a future version."
))
def get_current_workspace(workspace_id: str) -> Workspace

Get a Sandbox by its ID.

Arguments:

workspace_id str - The ID of the Sandbox to retrieve.

Returns:

Workspace - The Sandbox instance.

Daytona.get_current_sandbox

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

Get a Sandbox by its ID.

Arguments:

sandbox_id str - The ID of the Sandbox to retrieve.

Returns:

Sandbox - The Sandbox instance.

Raises:

DaytonaError - If sandbox_id is not provided.

Example:

sandbox = daytona.get_current_sandbox("my-sandbox-id")
print(sandbox.status)

Daytona.list

@intercept_errors(message_prefix="Failed to list sandboxes: ")
def list() -> List[Sandbox]

Lists all Sandboxes.

Returns:

List[Sandbox] - List of all available Sandbox instances.

Example:

sandboxes = daytona.list()
for sandbox in sandboxes:
    print(f"{sandbox.id}: {sandbox.status}")

Daytona.start

def start(sandbox: Sandbox, timeout: Optional[float] = 60) -> None

Starts a Sandbox and waits for it to be ready.

Arguments:

sandbox Sandbox - The Sandbox to start.
timeout Optional[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

def stop(sandbox: Sandbox, timeout: Optional[float] = 60) -> None

Stops a Sandbox and waits for it to be stopped.

Arguments:

sandbox Sandbox - The sandbox to stop
timeout Optional[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

Sandboxes are isolated development environments managed by Daytona. This guide covers how to create, manage, and remove Sandboxes using the SDK.

Examples:

Basic usage with environment variables:

from daytona_sdk import Daytona
# Initialize using environment variables
daytona = Daytona()  # Uses env vars DAYTONA_API_KEY, DAYTONA_SERVER_URL, DAYTONA_TARGET

# Create a default Python sandbox with custom environment variables
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    env_vars={"PYTHON_ENV": "development"}
))

# Execute commands in the sandbox
response = sandbox.process.execute_command('echo "Hello, World!"')
print(response.result)

# Run Python code securely inside the sandbox
response = sandbox.process.code_run('print("Hello from Python!")')
print(response.result)

# Remove the sandbox after use
daytona.remove(sandbox)

Usage with explicit configuration:

from daytona_sdk import Daytona, DaytonaConfig, CreateSandboxParams, SandboxResources

# Initialize with explicit configuration
config = DaytonaConfig(
    api_key="your-api-key",
    server_url="https://your-server.com",
    target="us"
)
daytona = Daytona(config)

# Create a custom sandbox with specific resources and settings
sandbox = daytona.create(CreateSandboxParams(
    language="python",
    image="python:3.11",
    resources=SandboxResources(
        cpu=2,
        memory=4,  # 4GB RAM
        disk=20    # 20GB disk
    ),
    env_vars={"PYTHON_ENV": "development"},
    auto_stop_interval=60  # Auto-stop after 1 hour of inactivity
))

# Use sandbox features
sandbox.git.clone("https://github.com/user/repo.git")
sandbox.process.execute_command("python -m pytest")

CodeLanguage

@dataclass
class CodeLanguage(Enum)

Programming languages supported by Daytona

DaytonaConfig

@dataclass
class DaytonaConfig()

Configuration options for initializing the Daytona client.

Attributes:

api_key Optional[str] - API key for authentication with Daytona server. If not set, it must be provided as environment variable DAYTONA_API_KEY.
server_url Optional[str] - URL of the Daytona server. Defaults to ‘https://app.daytona.io/api’ if not set.
target Optional[SandboxTargetRegion] - Target environment for Sandbox. Defaults to ‘us’ if not set.

Example:

# Only API key is required
config = DaytonaConfig(api_key="your-api-key")

SandboxResources

@dataclass
class SandboxResources()

Resources configuration for Sandbox.

Attributes:

cpu Optional[int] - Number of CPU cores to allocate.
memory Optional[int] - Amount of memory in GB to allocate.
disk Optional[int] - Amount of disk space in GB to allocate.
gpu Optional[int] - Number of GPUs to allocate.

Example:

resources = SandboxResources(
    cpu=2,
    memory=4,  # 4GB RAM
    disk=20,   # 20GB disk
    gpu=1
)
params = CreateSandboxParams(
    language="python",
    resources=resources
)

CreateSandboxParams

class CreateSandboxParams(BaseModel)

Parameters for creating a new Sandbox.

Attributes:

language Optional[CodeLanguage] - Programming language for the Sandbox (“python”, “javascript”, “typescript”). Defaults to “python”.
id Optional[str] - Custom identifier for the Sandbox. If not provided, a random ID will be generated.
name Optional[str] - Display name for the Sandbox. Defaults to Sandbox ID if not provided.
image Optional[str] - Custom Docker image to use for the Sandbox.
os_user Optional[str] - OS user for the Sandbox.
env_vars Optional[Dict[str, str]] - Environment variables to set in the Sandbox.
labels Optional[Dict[str, str]] - Custom labels for the Sandbox.
public Optional[bool] - Whether the Sandbox should be public.
target Optional[str] - Target location for the Sandbox. Can be “us”, “eu”, or “asia”.
resources Optional[SandboxResources] - Resource configuration for the Sandbox.
timeout Optional[float] - Timeout in seconds for Sandbox to be created and started.
auto_stop_interval Optional[int] - 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.

Example:

params = CreateSandboxParams(
    language="python",
    name="my-sandbox",
    env_vars={"DEBUG": "true"},
    resources=SandboxResources(cpu=2, memory=4),
    auto_stop_interval=20
)
sandbox = daytona.create(params, 50)

Sandbox Management

Daytona

Daytona.__init__

Daytona.create

Daytona.remove

Daytona.get_current_workspace

Daytona.get_current_sandbox

Daytona.list

Daytona.start

Daytona.stop

CodeLanguage

DaytonaConfig

SandboxResources

CreateSandboxParams

Daytona.init