Skip to content

Sandbox

The Daytona SDK core Sandbox functionality.

Provides the main Workspace class representing a Daytona Sandbox that coordinates file system, Git, process execution, and LSP functionality. It serves as the central point for interacting with Daytona Sandboxes.

Example:

Basic Sandbox operations:

from daytona_sdk import Daytona
daytona = Daytona()
workspace = daytona.create()


# File operations
workspace.fs.upload_file("/workspace/test.txt", b"Hello, World!")
content = workspace.fs.download_file("/workspace/test.txt")


# Git operations
workspace.git.clone("https://github.com/user/repo.git")


# Process execution
response = workspace.process.exec("ls -la")
print(response.result)


# LSP functionality
lsp = workspace.create_lsp_server("python", "/workspace/project")
lsp.did_open("/workspace/project/src/index.ts")
completions = lsp.completions("/workspace/project/src/index.ts", Position(line=10, character=15))
print(completions)

Notes:

The Sandbox must be in a ‘started’ state before performing operations.

Workspace

class Workspace()

[view_source]

Represents a Daytona Sandbox.

A Sandbox provides file system operations, Git operations, process execution, and LSP functionality. It serves as the main interface for interacting with a Daytona Sandbox.

Attributes:

  • id str - Unique identifier for the Sandbox.
  • instance WorkspaceInstance - The underlying Sandbox instance.
  • workspace_api WorkspaceApi - API client for Sandbox operations.
  • toolbox_api ToolboxApi - API client for toolbox operations.
  • code_toolbox WorkspaceCodeToolbox - Language-specific toolbox implementation.
  • fs FileSystem - File system operations interface.
  • git Git - Git operations interface.
  • process Process - Process execution interface.

Workspace.__init__

def __init__(id: str, instance: WorkspaceInstance, workspace_api: WorkspaceApi,
             toolbox_api: ToolboxApi, code_toolbox: WorkspaceCodeToolbox)

[view_source]

Initialize a new Workspace instance.

Arguments:

  • id str - Unique identifier for the Sandbox.
  • instance WorkspaceInstance - The underlying Sandbox instance.
  • workspace_api WorkspaceApi - API client for Sandbox operations.
  • toolbox_api ToolboxApi - API client for toolbox operations.
  • code_toolbox WorkspaceCodeToolbox - Language-specific toolbox implementation.

Workspace.info

def info() -> WorkspaceInfo

[view_source]

Gets structured information about the Sandbox.

Returns:

  • WorkspaceInfo - Detailed information about the Sandbox including its configuration, resources, and current state.

Example:

info = workspace.info()
print(f"Workspace {info.name}:")
print(f"State: {info.state}")
print(f"Resources: {info.resources.cpu} CPU, {info.resources.memory} RAM")

Workspace.get_workspace_root_dir

def get_workspace_root_dir() -> str

[view_source]

Gets the root directory path of the Sandbox.

Returns:

  • str - The absolute path to the Sandbox root directory.

Example:

root_dir = workspace.get_workspace_root_dir()
print(f"Workspace root: {root_dir}")

Workspace.create_lsp_server

def create_lsp_server(language_id: LspLanguageId,
                      path_to_project: str) -> LspServer

[view_source]

Creates a new Language Server Protocol (LSP) server instance.

The LSP server provides language-specific features like code completion, diagnostics, and more.

Arguments:

  • language_id LspLanguageId - The language server type (e.g., “python”, “typescript”).
  • path_to_project str - Absolute path to the project root directory.

Returns:

  • LspServer - A new LSP server instance configured for the specified language.

Example:

lsp = workspace.create_lsp_server("python", "/workspace/project")

Workspace.set_labels

def set_labels(labels: Dict[str, str]) -> Dict[str, str]

[view_source]

Sets labels for the Sandbox.

Labels are key-value pairs that can be used to organize and identify Sandboxes.

Arguments:

  • labels Dict[str, str] - Dictionary of key-value pairs representing Sandbox labels.

Returns:

Dict[str, str]: Dictionary containing the updated Sandbox labels.

Example:

new_labels = workspace.set_labels({
    "project": "my-project",
    "environment": "development",
    "team": "backend"
})
print(f"Updated labels: {new_labels}")

Workspace.start

def start(timeout: Optional[float] = None)

[view_source]

Starts the Sandbox.

This method starts the Sandbox and waits for it to be ready.

Arguments:

  • timeout Optional[float] - Maximum time to wait in seconds. 0 means no timeout. Defaults to 60-second timeout.

Raises:

  • ValueError - If timeout is negative.
  • Exception - If Sandbox fails to start or times out.

Example:

workspace = daytona.get_current_workspace("my-workspace")
workspace.start(timeout=40)  # Wait up to 40 seconds
print("Workspace started successfully")

Workspace.stop

def stop()

[view_source]

Stops the Sandbox.

This method stops the Sandbox and waits for it to be fully stopped.

Example:

workspace = daytona.get_current_workspace("my-workspace")
workspace.stop()
print("Workspace stopped successfully")

Workspace.wait_for_workspace_start

def wait_for_workspace_start(timeout: float = 60) -> None

[view_source]

Waits for the Sandbox to reach the ‘started’ state.

This method polls the Sandbox status until it reaches the ‘started’ state or encounters an error.

Arguments:

  • timeout float - Maximum time to wait in seconds. 0 means no timeout. Defaults to 60 seconds.

Raises:

  • ValueError - If timeout is negative.
  • Exception - If Sandbox fails to start or times out.

Workspace.wait_for_workspace_stop

def wait_for_workspace_stop() -> None

[view_source]

Waits for the Sandbox to reach the ‘stopped’ state.

This method polls the Sandbox status until it reaches the ‘stopped’ state or encounters an error. It will wait up to 60 seconds for the Sandbox to stop.

Raises:

  • Exception - If Sandbox fails to stop or times out.

Workspace.set_autostop_interval

def set_autostop_interval(interval: int) -> None

[view_source]

Sets the auto-stop interval for the Sandbox.

The Sandbox will automatically stop after being idle (no new events) for the specified interval. Events include any state changes or interactions with the Sandbox through the SDK. Interactions using Sandbox Previews are not included.

Arguments:

  • interval int - Number of minutes of inactivity before auto-stopping. Set to 0 to disable auto-stop. Defaults to 15.

Example:

# Auto-stop after 1 hour
workspace.set_autostop_interval(60)
# Or disable auto-stop
workspace.set_autostop_interval(0)

WorkspaceResources

@dataclass
class WorkspaceResources()

[view_source]

Resources allocated to a Sandbox.

Attributes:

  • cpu str - Number of CPU cores allocated (e.g., “1”, “2”).
  • gpu Optional[str] - Number of GPUs allocated (e.g., “1”) or None if no GPU.
  • memory str - Amount of memory allocated with unit (e.g., “2Gi”, “4Gi”).
  • disk str - Amount of disk space allocated with unit (e.g., “10Gi”, “20Gi”).

Example:

resources = WorkspaceResources(
    cpu="2",
    gpu="1",
    memory="4Gi",
    disk="20Gi"
)

WorkspaceInfo

@dataclass
class WorkspaceInfo()

[view_source]

Structured information about a Sandbox.

This class provides detailed information about a Sandbox’s configuration, resources, and current state.

Attributes:

  • id str - Unique identifier for the Sandbox.
  • name str - Display name of the Sandbox.
  • image str - Docker image used for the Sandbox.
  • user str - OS user running in the Sandbox.
  • env Dict[str, str] - Environment variables set in the Sandbox.
  • labels Dict[str, str] - Custom labels attached to the Sandbox.
  • public bool - Whether the Sandbox is publicly accessible.
  • target str - Target environment where the Sandbox runs.
  • resources WorkspaceResources - Resource allocations for the Sandbox.
  • state str - Current state of the Sandbox (e.g., “started”, “stopped”).
  • error_reason Optional[str] - Error message if Sandbox is in error state.
  • snapshot_state Optional[str] - Current state of Sandbox snapshot.
  • snapshot_state_created_at Optional[datetime] - When the snapshot state was created.

Example:

workspace = daytona.create()
info = workspace.info()
print(f"Workspace {info.name} is {info.state}")
print(f"Resources: {info.resources.cpu} CPU, {info.resources.memory} RAM")