Skip to content

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 workspace with custom environment variables
workspace = daytona.create(CreateWorkspaceParams(
    language="python",
    env_vars={"PYTHON_ENV": "development"}
))


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


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


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

Usage with explicit configuration:

from daytona_sdk import Daytona, DaytonaConfig, CreateWorkspaceParams, WorkspaceResources


# 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 workspace with specific resources and settings
workspace = daytona.create(CreateWorkspaceParams(
    language="python",
    image="python:3.11",
    resources=WorkspaceResources(
        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 workspace features
workspace.git.clone("https://github.com/user/repo.git")
workspace.process.execute_command("python -m pytest")

Daytona

class Daytona()

[view_source]

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)

[view_source]

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 “local”)

Arguments:

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

Raises:

  • ValueError - 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

def create(params: Optional[CreateWorkspaceParams] = None) -> Workspace

[view_source]

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[CreateWorkspaceParams] - Parameters for Sandbox creation. If not provided, defaults to Python language.

Returns:

  • Workspace - The created Sandbox instance.

Raises:

  • ValueError - If timeout or auto_stop_interval is negative.
  • Exception - If Sandbox creation fails.

Example:

Create a default Python Sandbox:

workspace = daytona.create()

Create a custom Sandbox:

params = CreateWorkspaceParams(
    language="python",
    name="my-workspace",
    image="debian:12.9",
    env_vars={"DEBUG": "true"},
    resources=WorkspaceResources(cpu=2, memory=4096),
    timeout=300,
    auto_stop_interval=0
)
workspace = daytona.create(params)

Daytona.remove

def remove(workspace: Workspace) -> None

[view_source]

Removes a Sandbox.

Arguments:

  • workspace Workspace - The Sandbox instance to remove.

Example:

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

Daytona.get_current_workspace

def get_current_workspace(workspace_id: str) -> Workspace

[view_source]

Get a Sandbox by its ID.

Arguments:

  • workspace_id str - The ID of the Sandbox to retrieve.

Returns:

  • Workspace - The Sandbox instance.

Raises:

  • ValueError - If workspace_id is not provided.

Example:

workspace = daytona.get_current_workspace("my-workspace-id")
print(workspace.status)

Daytona.list

def list() -> List[Workspace]

[view_source]

Lists all Sandboxes.

Returns:

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

Example:

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

Daytona.start

def start(workspace: Workspace, timeout: Optional[float] = None) -> None

[view_source]

Starts a Sandbox and waits for it to be ready.

Arguments:

  • workspace Workspace - The Sandbox to start.
  • timeout Optional[float] - Optional timeout in seconds to wait for the Sandbox to start. If set to 0, it will wait indefinitely.

Example:

workspace = daytona.get_current_workspace("my-workspace-id")
daytona.start(workspace, timeout=40)  # Wait up to 40 seconds

Daytona.stop

def stop(workspace: Workspace) -> None

[view_source]

Stops a Sandbox and waits for it to be stopped.

Arguments:

  • workspace Workspace - The Sandbox to stop.

Example:

workspace = daytona.get_current_workspace("my-workspace-id")
daytona.stop(workspace)

DaytonaConfig

@dataclass
class DaytonaConfig()

[view_source]

Configuration options for initializing the Daytona client.

Attributes:

  • api_key str - API key for authentication with Daytona server.
  • server_url str - URL of the Daytona server.
  • target str - Target environment for Sandbox.

Example:

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

WorkspaceResources

@dataclass
class WorkspaceResources()

[view_source]

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 = WorkspaceResources(
    cpu=2,
    memory=4,  # 4GB RAM
    disk=20,   # 20GB disk
    gpu=1
)
params = CreateWorkspaceParams(
    language="python",
    resources=resources
)

CreateWorkspaceParams

@dataclass
class CreateWorkspaceParams()

[view_source]

Parameters for creating a new Sandbox.

Attributes:

  • language CodeLanguage - Programming language for the Sandbox (“python”, “javascript”, “typescript”).
  • 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. Defaults to “daytona”.
  • 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[WorkspaceResources] - 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. If set to 0, the Sandbox will not be automatically stopped.

Example:

params = CreateWorkspaceParams(
    language="python",
    name="my-workspace",
    env_vars={"DEBUG": "true"},
    resources=WorkspaceResources(cpu=2, memory=4),
    timeout=60,
    auto_stop_interval=20
)
workspace = daytona.create(params)