Sandbox

The Daytona SDK core Sandbox functionality.

Provides the main Sandbox 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.

Examples:

Basic usage:

# Create and initialize sandbox
daytona = Daytona()
sandbox = daytona.create()

# File operations
sandbox.fs.upload_file(
    '/app/config.json',
    b'{"setting": "value"}'
)
content = sandbox.fs.download_file('/app/config.json')

# Git operations
sandbox.git.clone('https://github.com/user/repo.git')

# Process execution
response = sandbox.process.execute_command('ls -la')
print(response.result)

# LSP functionality
lsp = sandbox.create_lsp_server('python', '/workspace/project')
lsp.did_open('/workspace/project/src/main.py')
completions = lsp.completions('/workspace/project/src/main.py', {
    'line': 10,
    'character': 15
})
print(completions)

Sandbox

class Sandbox()

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 SandboxInstance - The underlying Sandbox instance.
code_toolbox SandboxCodeToolbox - Language-specific toolbox implementation.
fs FileSystem - File system operations interface.
git Git - Git operations interface.
process Process - Process execution interface.

Sandbox.init

def __init__(id: str, instance: SandboxInstance, sandbox_api: SandboxApi,
             toolbox_api: ToolboxApi, code_toolbox: SandboxCodeToolbox)

Initialize a new Sandbox instance.

Arguments:

id str - Unique identifier for the Sandbox.
instance SandboxInstance - The underlying Sandbox instance.
sandbox_api SandboxApi - API client for Sandbox operations.
toolbox_api ToolboxApi - API client for toolbox operations.
code_toolbox SandboxCodeToolbox - Language-specific toolbox implementation.

Sandbox.info

def info() -> SandboxInfo

Gets structured information about the Sandbox.

Returns:

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

Example:

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

Sandbox.get_user_root_dir

@intercept_errors(message_prefix="Failed to get sandbox root directory: ")
def get_user_root_dir() -> str

Gets the root directory path for the logged in user inside the Sandbox.

Returns:

str - The absolute path to the Sandbox root directory for the logged in user.

Example:

root_dir = sandbox.get_user_root_dir()
print(f"Sandbox root: {root_dir}")

Sandbox.create_lsp_server

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

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., LspLanguageId.PYTHON).
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 = sandbox.create_lsp_server("python", "/workspace/project")

Sandbox.set_labels

@intercept_errors(message_prefix="Failed to set labels: ")
def set_labels(labels: Dict[str, str]) -> Dict[str, str]

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 = sandbox.set_labels({
    "project": "my-project",
    "environment": "development",
    "team": "backend"
})
print(f"Updated labels: {new_labels}")

Sandbox.start

@intercept_errors(message_prefix="Failed to start sandbox: ")
@with_timeout(error_message=lambda self, timeout: (
    f"Sandbox {self.id} failed to start within the {timeout} seconds timeout period"
))
def start(timeout: Optional[float] = 60)

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. Default is 60 seconds.

Raises:

DaytonaError - If timeout is negative. If sandbox fails to start or times out.

Example:

sandbox = daytona.get_current_sandbox("my-sandbox")
sandbox.start(timeout=40)  # Wait up to 40 seconds
print("Sandbox started successfully")

Sandbox.stop

@intercept_errors(message_prefix="Failed to stop sandbox: ")
@with_timeout(error_message=lambda self, timeout: (
    f"Sandbox {self.id} failed to stop within the {timeout} seconds timeout period"
))
def stop(timeout: Optional[float] = 60)

Stops the Sandbox.

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

Arguments:

timeout Optional[float] - Maximum time to wait in seconds. 0 means no timeout. Default is 60 seconds.

Raises:

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

Example:

sandbox = daytona.get_current_sandbox("my-sandbox")
sandbox.stop()
print("Sandbox stopped successfully")

Sandbox.wait_for_workspace_start

@deprecated(reason=(
    "Method is deprecated. Use `wait_for_sandbox_start` instead. This method will be removed in a future"
    " version."))
def wait_for_workspace_start(timeout: Optional[float] = 60) -> None

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 Optional[float] - Maximum time to wait in seconds. 0 means no timeout. Default is 60 seconds.

Raises:

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

Sandbox.wait_for_sandbox_start

@intercept_errors(
    message_prefix="Failure during waiting for sandbox to start: ")
@with_timeout(error_message=lambda self, timeout: (
    f"Sandbox {self.id} failed to become ready within the {timeout} seconds timeout period"
))
def wait_for_sandbox_start(timeout: Optional[float] = 60) -> None

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 Optional[float] - Maximum time to wait in seconds. 0 means no timeout. Default is 60 seconds.

Raises:

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

Sandbox.wait_for_workspace_stop

@deprecated(reason=(
    "Method is deprecated. Use `wait_for_sandbox_stop` instead. This method will be removed in a future"
    " version."))
def wait_for_workspace_stop(timeout: Optional[float] = 60) -> None

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.

Arguments:

timeout Optional[float] - Maximum time to wait in seconds. 0 means no timeout. Default is 60 seconds.

Raises:

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

Sandbox.wait_for_sandbox_stop

@intercept_errors(
    message_prefix="Failure during waiting for sandbox to stop: ")
@with_timeout(error_message=lambda self, timeout: (
    f"Sandbox {self.id} failed to become stopped within the {timeout} seconds timeout period"
))
def wait_for_sandbox_stop(timeout: Optional[float] = 60) -> None

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.

Arguments:

timeout Optional[float] - Maximum time to wait in seconds. 0 means no timeout. Default is 60 seconds.

Raises:

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

Sandbox.set_autostop_interval

@intercept_errors(message_prefix="Failed to set auto-stop interval: ")
def set_autostop_interval(interval: int) -> None

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.

Raises:

DaytonaError - If interval is negative

Example:

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

Sandbox.get_preview_link

@intercept_errors(message_prefix="Failed to get preview link: ")
def get_preview_link(port: int) -> str

Gets the preview link for the sandbox at a specific port. If the port is not open, it will open it and return the link.

Arguments:

port int - The port to open the preview link on

Returns:

The preview link for the sandbox at the specified port

Sandbox.archive

@intercept_errors(message_prefix="Failed to archive sandbox: ")
def archive() -> None

Archives the sandbox, making it inactive and preserving its state. When sandboxes are archived, the entire filesystem state is moved to cost-effective object storage, making it possible to keep sandboxes available for an extended period. The tradeoff between archived and stopped states is that starting an archived sandbox takes more time, depending on its size. Sandbox must be stopped before archiving.

Sandbox.to_sandbox_info

@staticmethod
def to_sandbox_info(instance: ApiSandbox) -> SandboxInfo

Converts an API sandbox instance to a SandboxInfo object.

Arguments:

instance ApiSandbox - The API sandbox instance to convert

Returns:

SandboxInfo - The converted SandboxInfo object

The Daytona SDK core Sandbox functionality.

Examples:

Basic usage:

# Create and initialize sandbox
daytona = Daytona()
sandbox = daytona.create()

# File operations
sandbox.fs.upload_file(
    '/app/config.json',
    b'{"setting": "value"}'
)
content = sandbox.fs.download_file('/app/config.json')

# Git operations
sandbox.git.clone('https://github.com/user/repo.git')

# Process execution
response = sandbox.process.execute_command('ls -la')
print(response.result)

# LSP functionality
lsp = sandbox.create_lsp_server('python', '/workspace/project')
lsp.did_open('/workspace/project/src/main.py')
completions = lsp.completions('/workspace/project/src/main.py', {
    'line': 10,
    'character': 15
})
print(completions)

SandboxTargetRegion

@dataclass
class SandboxTargetRegion(Enum)

Target regions for Sandboxes

SandboxResources

@dataclass
class SandboxResources()

Resources allocated to a Sandbox.

Attributes:

cpu str - Nu, “1”, “2”).
gpu Optional[str] - Number of GPUs allocated mber of CPU cores allocated (e.g.(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 = SandboxResources(
    cpu="2",
    gpu="1",
    memory="4Gi",
    disk="20Gi"
)

SandboxInfo

class SandboxInfo(ApiSandboxInfo)

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 SandboxResources - 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:

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

SandboxInstance

class SandboxInstance(ApiSandbox)

Represents a Daytona Sandbox instance.

Sandbox

Sandbox

Sandbox.__init__

Sandbox.info

Sandbox.get_user_root_dir

Sandbox.create_lsp_server

Sandbox.set_labels

Sandbox.start

Sandbox.stop

Sandbox.wait_for_workspace_start

Sandbox.wait_for_sandbox_start

Sandbox.wait_for_workspace_stop

Sandbox.wait_for_sandbox_stop

Sandbox.set_autostop_interval

Sandbox.get_preview_link

Sandbox.archive

Sandbox.to_sandbox_info

SandboxTargetRegion

SandboxResources

SandboxInfo

SandboxInstance

Sandbox.init