# koyeb.sandbox Koyeb Sandbox - Interactive execution environment for running arbitrary code on Koyeb # koyeb.sandbox.sandbox Koyeb Sandbox - Python SDK for creating and managing Koyeb sandboxes #### DEFAULT\_INSTANCE\_WAIT\_TIMEOUT seconds #### DEFAULT\_POLL\_INTERVAL seconds #### FAST\_POLL\_INTERVAL seconds #### FAST\_POLL\_WINDOW seconds after wait_ready() starts ## ProcessInfo Objects ```python @dataclass class ProcessInfo() ``` Type definition for process information returned by list_processes. #### id Process ID (UUID string) #### command The command that was executed #### status Process status (e.g., "running", "completed") #### pid OS process ID (if running) #### exit\_code Exit code (if completed) #### started\_at ISO 8601 timestamp when process started #### completed\_at ISO 8601 timestamp when process completed (if applicable) ## ExposedPort Objects ```python @dataclass class ExposedPort() ``` Result of exposing a port via TCP proxy. #### validate\_port ```python def validate_port(port: int) -> None ``` Validate that a port number is in the valid range. **Arguments**: - `port` - Port number to validate **Raises**: - `ValueError` - If port is not in valid range [1, 65535] ## Sandbox Objects ```python class Sandbox() ``` Synchronous sandbox for running code on Koyeb infrastructure. Provides creation and deletion functionality with proper health polling. #### id ```python @property def id() -> str ``` Get the service ID of the sandbox. #### create ```python @classmethod def create(cls, image: str = "koyeb/sandbox", name: str = "quick-sandbox", wait_ready: bool = True, instance_type: str = "micro", exposed_port_protocol: Optional[str] = None, env: Optional[Dict[str, Any]] = None, config_files: Optional[Dict[str, Any]] = None, region: Optional[str] = None, api_token: Optional[str] = None, timeout: int = 300, idle_timeout: int = 300, enable_tcp_proxy: bool = False, privileged: bool = False, registry_secret: Optional[str] = None, _experimental_enable_light_sleep: bool = False, _experimental_deep_sleep_value: int = 3900, delete_after_delay: int = 0, delete_after_inactivity_delay: int = 0, app_id: Optional[str] = None, enable_mesh: Optional[bool] = None, poll_interval: float = DEFAULT_POLL_INTERVAL, entrypoint: Optional[List[str]] = None, command: Optional[str] = None, args: Optional[List[str]] = None, host: Optional[str] = None, block_network: bool = False, outbound_allowlist: Optional[List[str]] = None, snapshot: Optional[Union[str, "Snapshot"]] = None, sandbox_secret: Optional[str] = None, cleanup_on_failure: bool = True) -> Sandbox ``` Create a new sandbox instance. **Arguments**: - `image` - Docker image to use (default: koyeb/sandbox) - `name` - Name of the sandbox - `wait_ready` - Wait for sandbox to be ready (default: True) - `instance_type` - Instance type (default: micro) - `exposed_port_protocol` - Protocol to expose ports with ("http" or "http2"). If None, defaults to "http". If provided, must be one of "http" or "http2". - `env` - Environment variables - `config_files` - Config files to create in the sandbox, as a dictionary mapping file paths to file contents. Values can be plain strings (default permissions 0644) or ``ConfigFile`` instances for custom permissions (e.g., {"/etc/myapp/config.yaml": "key: value", "/etc/myapp/cert.pem": ConfigFile(content="...", permissions="0600")}) - `region` - Region to deploy to. Defaults to KOYEB_REGION env var, or "na" if not set. - `api_token` - Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var) - `timeout` - Timeout for sandbox creation in seconds - `idle_timeout` - Sleep timeout in seconds. Behavior depends on _experimental_enable_light_sleep: - If _experimental_enable_light_sleep is True: sets light_sleep value (deep_sleep=3900) - If _experimental_enable_light_sleep is False: sets deep_sleep value - If 0: disables scale-to-zero (keep always-on) - `enable_tcp_proxy` - If True, enables TCP proxy for direct TCP access to port 3031 - `privileged` - If True, run the container in privileged mode (default: False) - `registry_secret` - Name of a Koyeb secret containing registry credentials for pulling private images. Create the secret via Koyeb dashboard or CLI first. - `_experimental_enable_light_sleep` - If True, uses idle_timeout for light_sleep and sets deep_sleep=3900. If False, uses idle_timeout for deep_sleep (default: False) - `delete_after_delay` - If >0, automatically delete the sandbox if there was no activity after this many seconds since creation. - `delete_after_inactivity_delay` - If >0, automatically delete the sandbox if service sleeps due to inactivity after this many seconds. - `app_id` - If provided, create the sandbox service in an existing app instead of creating a new one. - `enable_mesh` - Mesh tri-state: None (default) = auto, True = enabled, False = disabled - `poll_interval` - Time between health checks in seconds when wait_ready is True (default: 0.5) - `entrypoint` - Override the default entrypoint of the Docker image (e.g., ["/bin/sh", "-c"]) - `command` - Override the default command of the Docker image (e.g., "python app.py") - `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com) - `block_network` - If True, block all outbound network access from the sandbox - `outbound_allowlist` - List of IPs/CIDRs allowed as outbound destinations; all other outbound traffic is blocked. Bare IPs are normalized to /32 (IPv4) or /128 (IPv6). Mutually exclusive with block_network. - `snapshot` - Optional. A Snapshot object or snapshot name/ID string to create the sandbox from. If provided, the sandbox will be initialized from this snapshot. Can be either a Snapshot object (e.g., snapshot=my_snapshot) or a snapshot name/ID string (e.g., snapshot="my snapshot"). - `sandbox_secret` - Optional sandbox secret to use for executor authentication. If not provided, a new one will be generated. **Returns**: - `Sandbox` - A new Sandbox instance **Raises**: - `ValueError` - If API token is not provided - `SandboxTimeoutError` - If wait_ready is True and sandbox does not become ready within timeout - `EgressPolicyError` - If both block_network and outbound_allowlist are passed, or an allowlist entry is not a valid IP address or CIDR **Example**: >>> # Public image (default) >>> sandbox = Sandbox.create() >>> # Private image with registry secret >>> sandbox = Sandbox.create( ... image="ghcr.io/myorg/myimage:latest", ... registry_secret="my-ghcr-secret" ... ) >>> # Create from a Snapshot object >>> from koyeb.sandbox import Snapshot >>> snapshot = Snapshot.get("my-snapshot-id") >>> sandbox = Sandbox.create(snapshot=snapshot) >>> # Create from a snapshot ID string >>> sandbox = Sandbox.create(snapshot="my-snapshot-id") >>> # Create from a snapshot with custom parameters >>> sandbox = Sandbox.create( ... snapshot="my-snapshot-id", ... image="python:3.12", ... instance_type="nano", ... env={"MY_VAR": "value"} ... ) #### get\_from\_id ```python @classmethod def get_from_id(cls, id: str, api_token: Optional[str] = None, host: Optional[str] = None) -> "Sandbox" ``` Get a sandbox by service ID. **Arguments**: - `id` - Service ID of the sandbox - `api_token` - Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var) - `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com) **Returns**: - `Sandbox` - The Sandbox instance **Raises**: - `ValueError` - If API token is not provided or id is invalid - `SandboxError` - If sandbox is not found or retrieval fails #### list ```python @classmethod def list(cls, app_id: Optional[str] = None, name: Optional[str] = None, api_token: Optional[str] = None, host: Optional[str] = None) -> List["Sandbox"] ``` List sandbox services. Paginates services of type SANDBOX (100 per page, mirroring the CLI). Returns lazily-connected handles: they carry no executor secret, so connected operations raise NoSandboxSecretError — use ``Sandbox.get_from_id(handle.id)`` for a connected handle. **Arguments**: - `app_id` - Optional app filter - `name` - Optional name filter - `api_token` - Koyeb API token (defaults to KOYEB_API_TOKEN env var) - `host` - Koyeb API host (defaults to KOYEB_API_HOST env var) **Returns**: - `List[Sandbox]` - Lazy handles for every sandbox service #### snapshot ```python def snapshot(name: str, snapshot_type: Optional["SnapshotType"] = None, wait_available: bool = True, timeout: int = 600) -> "Snapshot" ``` Create a snapshot of this sandbox. Captures the current state of the sandbox's filesystem (and optionally running processes for FULL type) so it can be restored later. **Arguments**: - `name` - Name for the snapshot - `snapshot_type` - Type of snapshot to create (FILESYSTEM or FULL). Defaults to FILESYSTEM. - `wait_available` - Whether to wait for snapshot to become available - `timeout` - Timeout in seconds for waiting **Returns**: - `Snapshot` - The created snapshot object **Raises**: - `SandboxError` - If snapshot creation fails #### create\_from\_snapshot ```python @classmethod def create_from_snapshot(cls, snapshot: Union["Snapshot", str], name: Optional[str] = None, wait_ready: bool = True, timeout: int = 300, **create_kwargs) -> "Sandbox" ``` Create a new sandbox from a snapshot. **Arguments**: - `snapshot` - Snapshot object or snapshot ID string - `name` - Name for the new sandbox - `wait_ready` - Whether to wait for sandbox to be ready - `timeout` - Timeout in seconds - `**create_kwargs` - Additional arguments to pass to create() **Returns**: - `Sandbox` - A new sandbox instance #### template ```python @classmethod def template(cls, name: str, image: str, workdir: Optional[str] = None, api_token: Optional[str] = None, host: Optional[str] = None, delete_builder: bool = True) -> "DeclarativeSnapshot" ``` Create a declarative snapshot builder. Use this to build a reusable snapshot by declaratively defining the sandbox environment (files, packages, etc.) and then building a snapshot that can be used to spawn pre-configured sandboxes. **Arguments**: - `name` - Name for the template - `image` - Docker image to use - `workdir` - Working directory in the sandbox - `api_token` - Koyeb API token - `host` - Koyeb API host - `delete_builder` - Whether to delete the builder sandbox after creating the snapshot (default: True) **Returns**: - `DeclarativeSnapshot` - Fluent builder for creating snapshots **Example**: snapshot = ( Sandbox.template("python-ci", image="python:3.12", workdir="/workspace") .file("requirements.txt", "pytest\nrequests") .run("pip install -r requirements.txt") .build(snapshot_name="python-ci-env") ) sbx = snapshot.spawn(name="test-runner") #### wait\_ready ```python def wait_ready(timeout: int = DEFAULT_INSTANCE_WAIT_TIMEOUT, poll_interval: Optional[float] = None) -> bool ``` Wait for sandbox to become ready with exponential backoff polling. First waits for the deployment status to become HEALTHY, then polls the sandbox health endpoint to confirm the executor is responsive. Polls every 0.1s for the first 10s, then doubles the interval each time up to poll_interval. **Arguments**: - `timeout` - Maximum time to wait in seconds - `poll_interval` - Maximum time between health checks in seconds (defaults to instance poll_interval) **Returns**: - `bool` - True if sandbox became ready, False if timeout #### wait\_tcp\_proxy\_ready ```python def wait_tcp_proxy_ready(timeout: int = DEFAULT_INSTANCE_WAIT_TIMEOUT, poll_interval: Optional[float] = None) -> bool ``` Wait for TCP proxy to become ready and available. Polls the deployment metadata with exponential backoff until the TCP proxy information is available. Starts at 0.1s intervals, doubling up to poll_interval. **Arguments**: - `timeout` - Maximum time to wait in seconds - `poll_interval` - Maximum time between checks in seconds (defaults to instance poll_interval) **Returns**: - `bool` - True if TCP proxy became ready, False if timeout #### delete ```python def delete() -> None ``` Delete the sandbox instance. Deletes the whole app for SDK-created sandboxes; only the service when the sandbox lives in a caller-provided app. #### get\_domain ```python def get_domain() -> Optional[str] ``` Get the public domain of the sandbox. Returns the domain (e.g., "app-name-org.koyeb.app/r/routing_key/" or "app-name-org.koyeb.app") without protocol. To get the full URL with protocol, use sandbox._get_url() **Returns**: - `Optional[str]` - The domain or None if unavailable #### get\_tcp\_proxy\_info ```python def get_tcp_proxy_info() -> Optional[tuple[str, int]] ``` Get the TCP proxy host and port for the sandbox. Returns the TCP proxy host and port as a tuple (host, port) for direct TCP access to port 3031. This is only available if enable_tcp_proxy=True was set when creating the sandbox. **Returns**: Optional[tuple[str, int]]: A tuple of (host, port) or None if unavailable #### is\_healthy ```python def is_healthy() -> bool ``` Check if sandbox is healthy and ready for operations. Raises SandboxDeploymentError when the deployment reached a terminal state (e.g. STOPPED) — classification fails closed. #### filesystem ```python @property def filesystem() -> "SandboxFilesystem" ``` Get filesystem operations interface #### exec ```python @property def exec() -> "SandboxExecutor" ``` Get command execution interface #### expose\_port ```python def expose_port(port: int) -> ExposedPort ``` Expose a port to external connections via TCP proxy. Binds the specified internal port to the TCP proxy, allowing external connections to reach services running on that port inside the sandbox. Automatically unbinds any existing port before binding the new one. **Arguments**: - `port` - The internal port number to expose (must be a valid port number between 1 and 65535) **Returns**: - `ExposedPort` - An object with `port` and `exposed_at` attributes: - port: The exposed port number - exposed_at: The full URL with https:// protocol (e.g., "https://app-name-org.koyeb.app") **Raises**: - `ValueError` - If port is not in valid range [1, 65535] - `SandboxError` - If the port binding operation fails **Notes**: - Only one port can be exposed at a time - Any existing port binding is automatically unbound before binding the new port - The port must be available and accessible within the sandbox environment - The TCP proxy is accessed via get_tcp_proxy_info() which returns (host, port) **Example**: >>> result = sandbox.expose_port(8080) >>> result.port 8080 >>> result.exposed_at 'https://app-name-org.koyeb.app' #### unexpose\_port ```python def unexpose_port() -> None ``` Unexpose a port from external connections. Removes the TCP proxy port binding, stopping traffic forwarding to the previously bound port. **Raises**: - `SandboxError` - If the port unbinding operation fails **Notes**: - After unexposing, the TCP proxy will no longer forward traffic - Safe to call even if no port is currently bound #### launch\_process ```python def launch_process(cmd: str, cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None) -> str ``` Launch a background process in the sandbox. Starts a long-running background process that continues executing even after the method returns. Use this for servers, workers, or other long-running tasks. **Arguments**: - `cmd` - The shell command to execute as a background process - `cwd` - Optional working directory for the process - `env` - Optional environment variables to set/override for the process **Returns**: - `str` - The unique process ID (UUID string) that can be used to manage the process **Raises**: - `SandboxError` - If the process launch fails **Example**: >>> process_id = sandbox.launch_process("python -u server.py") >>> print(f"Started process: {process_id}") #### kill\_process ```python def kill_process(process_id: str) -> None ``` Kill a background process by its ID. Terminates a running background process. This sends a SIGTERM signal to the process, allowing it to clean up gracefully. If the process doesn't terminate within a timeout, it will be forcefully killed with SIGKILL. **Arguments**: - `process_id` - The unique process ID (UUID string) to kill **Raises**: - `SandboxError` - If the process kill operation fails **Example**: >>> sandbox.kill_process("550e8400-e29b-41d4-a716-446655440000") #### list\_processes ```python def list_processes() -> List[ProcessInfo] ``` List all background processes. Returns information about all currently running and recently completed background processes. This includes both active processes and processes that have completed (which remain in memory until server restart). **Returns**: - `List[ProcessInfo]` - List of process objects, each containing: - id: Process ID (UUID string) - command: The command that was executed - status: Process status (e.g., "running", "completed") - pid: OS process ID (if running) - exit_code: Exit code (if completed) - started_at: ISO 8601 timestamp when process started - completed_at: ISO 8601 timestamp when process completed (if applicable) **Raises**: - `SandboxError` - If listing processes fails **Example**: >>> processes = sandbox.list_processes() >>> for process in processes: ... print(f"{process.id}: {process.command} - {process.status}") #### kill\_all\_processes ```python def kill_all_processes() -> int ``` Kill all running background processes. Convenience method that lists all processes and kills them all. This is useful for cleanup operations. **Returns**: - `int` - The number of processes that were killed **Raises**: - `SandboxError` - If listing or killing processes fails **Example**: >>> count = sandbox.kill_all_processes() >>> print(f"Killed {count} processes") #### update\_lifecycle ```python def update_lifecycle(delete_after_delay: Optional[int] = None, delete_after_inactivity: Optional[int] = None) -> None ``` Update the sandbox's life cycle settings. **Arguments**: - `delete_after_delay` - If >0, automatically delete the sandbox if there was no activity after this many seconds since creation. - `delete_after_inactivity` - If >0, automatically delete the sandbox if service sleeps due to inactivity after this many seconds. **Raises**: - `SandboxError` - If updating life cycle fails **Example**: >>> sandbox.update_life_cycle(delete_after_delay=600, delete_after_inactivity=300) #### update\_network\_policy ```python def update_network_policy( block_network: bool = False, outbound_allowlist: Optional[List[str]] = None) -> None ``` Update the sandbox's network policy. Warning: applying a new network policy triggers a redeployment of the sandbox service. The sandbox is restarted and any in-memory or non-persisted state is lost. This method does not wait for the redeployment to finish; it repoints the sandbox at the new deployment and clears cached connection state, so call wait_ready() afterwards to block until the replacement deployment is healthy before issuing further operations. **Arguments**: - `block_network` - If True, block all outbound network access from the sandbox - `outbound_allowlist` - List of IPs/CIDRs allowed as outbound destinations; all other outbound traffic is blocked. Bare IPs are normalized to /32 (IPv4) or /128 (IPv6). Mutually exclusive with block_network. With both arguments unset, the network policy is reset to the platform default (unrestricted outbound access). **Raises**: - `EgressPolicyError` - If both block_network and outbound_allowlist are passed, or an allowlist entry is not a valid IP address or CIDR - `SandboxError` - If updating the network policy fails **Example**: >>> sandbox.update_network_policy(block_network=True) >>> sandbox.update_network_policy(outbound_allowlist=["10.0.0.0/8", "1.2.3.4"]) >>> sandbox.update_network_policy() # reset to unrestricted #### \_\_enter\_\_ ```python def __enter__() -> "Sandbox" ``` Context manager entry - returns self. #### \_\_exit\_\_ ```python def __exit__(exc_type, exc_val, exc_tb) -> None ``` Context manager exit - automatically deletes the sandbox. ## AsyncSandbox Objects ```python class AsyncSandbox(Sandbox) ``` Async sandbox for running code on Koyeb infrastructure. Inherits from Sandbox and provides native async implementations. #### get\_from\_id ```python @classmethod async def get_from_id(cls, id: str, api_token: Optional[str] = None, host: Optional[str] = None) -> "AsyncSandbox" ``` Get a sandbox by service ID asynchronously. **Arguments**: - `id` - Service ID of the sandbox - `api_token` - Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var) - `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com) **Returns**: - `AsyncSandbox` - The AsyncSandbox instance **Raises**: - `ValueError` - If API token is not provided or id is invalid - `SandboxError` - If sandbox is not found or retrieval fails #### create ```python @classmethod async def create(cls, image: str = "koyeb/sandbox", name: str = "quick-sandbox", wait_ready: bool = True, instance_type: str = "micro", exposed_port_protocol: Optional[str] = None, env: Optional[Dict[str, Any]] = None, config_files: Optional[Dict[str, Any]] = None, region: Optional[str] = None, api_token: Optional[str] = None, timeout: int = 300, idle_timeout: int = 300, enable_tcp_proxy: bool = False, privileged: bool = False, registry_secret: Optional[str] = None, _experimental_enable_light_sleep: bool = False, _experimental_deep_sleep_value: int = 3900, delete_after_delay: int = 0, delete_after_inactivity_delay: int = 0, app_id: Optional[str] = None, enable_mesh: Optional[bool] = None, poll_interval: float = DEFAULT_POLL_INTERVAL, entrypoint: Optional[List[str]] = None, command: Optional[str] = None, args: Optional[List[str]] = None, host: Optional[str] = None, block_network: bool = False, outbound_allowlist: Optional[List[str]] = None, snapshot: Optional[Union[str, "Snapshot"]] = None, sandbox_secret: Optional[str] = None, cleanup_on_failure: bool = True) -> AsyncSandbox ``` Create a new sandbox instance with async support. **Arguments**: - `image` - Docker image to use (default: koyeb/sandbox) - `name` - Name of the sandbox - `wait_ready` - Wait for sandbox to be ready (default: True) - `instance_type` - Instance type (default: micro) - `exposed_port_protocol` - Protocol to expose ports with ("http" or "http2"). If None, defaults to "http". If provided, must be one of "http" or "http2". - `env` - Environment variables - `config_files` - Config files to create in the sandbox, as a dictionary mapping file paths to file contents. Values can be plain strings (default permissions 0644) or ``ConfigFile`` instances for custom permissions (e.g., {"/etc/myapp/config.yaml": "key: value", "/etc/myapp/cert.pem": ConfigFile(content="...", permissions="0600")}) - `region` - Region to deploy to. Defaults to KOYEB_REGION env var, or "na" if not set. - `api_token` - Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var) - `timeout` - Timeout for sandbox creation in seconds - `idle_timeout` - Sleep timeout in seconds. Behavior depends on _experimental_enable_light_sleep: - If _experimental_enable_light_sleep is True: sets light_sleep value (deep_sleep uses _experimental_deep_sleep_value) - If _experimental_enable_light_sleep is False: sets deep_sleep value - If 0: disables scale-to-zero (keep always-on) - `enable_tcp_proxy` - If True, enables TCP proxy for direct TCP access to port 3031 - `privileged` - If True, run the container in privileged mode (default: False) - `registry_secret` - Name of a Koyeb secret containing registry credentials for pulling private images. Create the secret via Koyeb dashboard or CLI first. - `_experimental_enable_light_sleep` - If True, uses idle_timeout for light_sleep and configurable deep_sleep (default: False) - `_experimental_deep_sleep_value` - Number of seconds for deep sleep when light sleep is enabled (default: 3900). Only used if _experimental_enable_light_sleep is True - `delete_after_delay` - If >0, automatically delete the sandbox if there was no activity after this many seconds since creation. - `delete_after_inactivity_delay` - If >0, automatically delete the sandbox if service sleeps due to inactivity after this many seconds. - `app_id` - If provided, create the sandbox service in an existing app instead of creating a new one. - `enable_mesh` - Mesh tri-state: None (default) = auto, True = enabled, False = disabled - `poll_interval` - Time between health checks in seconds when wait_ready is True (default: 0.5) - `entrypoint` - Override the default entrypoint of the Docker image (e.g., ["/bin/sh", "-c"]) - `command` - Override the default command of the Docker image (e.g., "python app.py") - `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com) - `block_network` - If True, block all outbound network access from the sandbox - `outbound_allowlist` - List of IPs/CIDRs allowed as outbound destinations; all other outbound traffic is blocked. Bare IPs are normalized to /32 (IPv4) or /128 (IPv6). Mutually exclusive with block_network. - `snapshot` - Optional. A Snapshot object or snapshot name/ID string to create the sandbox from. If provided, the sandbox will be initialized from this snapshot. Can be either a Snapshot object (e.g., snapshot=my_snapshot) or a snapshot name/ID string (e.g., snapshot="my snapshot"). - `sandbox_secret` - Optional sandbox secret to use for executor authentication. If not provided, a new one will be generated. **Returns**: - `AsyncSandbox` - A new AsyncSandbox instance **Raises**: - `ValueError` - If API token is not provided - `SandboxTimeoutError` - If wait_ready is True and sandbox does not become ready within timeout - `EgressPolicyError` - If both block_network and outbound_allowlist are passed, or an allowlist entry is not a valid IP address or CIDR #### list ```python @classmethod async def list(cls, app_id: Optional[str] = None, name: Optional[str] = None, api_token: Optional[str] = None, host: Optional[str] = None) -> List["AsyncSandbox"] ``` List sandbox services (async twin of :meth:`Sandbox.list`). Returns lazily-connected handles without executor secrets; use ``AsyncSandbox.get_from_id(handle.id)`` for a connected handle. #### wait\_ready ```python async def wait_ready(timeout: int = DEFAULT_INSTANCE_WAIT_TIMEOUT, poll_interval: Optional[float] = None) -> bool ``` Wait for sandbox to become ready with exponential backoff async polling. First waits for the deployment status to become HEALTHY, then polls the sandbox health endpoint to confirm the executor is responsive. Polls every 0.1s for the first 10s, then doubles the interval each time up to poll_interval. **Arguments**: - `timeout` - Maximum time to wait in seconds - `poll_interval` - Maximum time between health checks in seconds (defaults to instance poll_interval) **Returns**: - `bool` - True if sandbox became ready, False if timeout #### wait\_tcp\_proxy\_ready ```python async def wait_tcp_proxy_ready(timeout: int = DEFAULT_INSTANCE_WAIT_TIMEOUT, poll_interval: Optional[float] = None) -> bool ``` Wait for TCP proxy to become ready and available asynchronously. Polls the deployment metadata with exponential backoff until the TCP proxy information is available. Starts at 0.1s intervals, doubling up to poll_interval. **Arguments**: - `timeout` - Maximum time to wait in seconds - `poll_interval` - Maximum time between checks in seconds (defaults to instance poll_interval) **Returns**: - `bool` - True if TCP proxy became ready, False if timeout #### delete ```python async def delete() -> None ``` Delete the sandbox instance asynchronously. Deletes the whole app for SDK-created sandboxes; only the service when the sandbox lives in a caller-provided app. #### snapshot ```python async def snapshot(name: str, snapshot_type: Optional["SnapshotType"] = None, wait_available: bool = True, timeout: int = 600) -> "Snapshot" ``` Create a snapshot of this sandbox asynchronously. Captures the current state of the sandbox's filesystem (and optionally running processes for FULL type) so it can be restored later. **Arguments**: - `name` - Name for the snapshot - `snapshot_type` - Type of snapshot to create (FILESYSTEM or FULL). Defaults to FILESYSTEM. - `wait_available` - Whether to wait for snapshot to become available - `timeout` - Timeout in seconds for waiting **Returns**: - `Snapshot` - The created snapshot object **Raises**: - `SandboxError` - If snapshot creation fails #### create\_from\_snapshot ```python @classmethod async def create_from_snapshot(cls, snapshot: Union["Snapshot", str], name: Optional[str] = None, wait_ready: bool = True, timeout: int = 300, **create_kwargs) -> "AsyncSandbox" ``` Create a new async sandbox from a snapshot. **Arguments**: - `snapshot` - Snapshot object or snapshot ID string - `name` - Name for the new sandbox - `wait_ready` - Whether to wait for sandbox to be ready - `timeout` - Timeout in seconds - `**create_kwargs` - Additional arguments to pass to create() **Returns**: - `AsyncSandbox` - A new async sandbox instance #### is\_healthy ```python async def is_healthy() -> bool ``` Check if sandbox is healthy and ready for operations asynchronously. Raises SandboxDeploymentError when the deployment reached a terminal state (e.g. STOPPED) — classification fails closed. #### exec ```python @property def exec() -> "AsyncSandboxExecutor" ``` Get async command execution interface #### filesystem ```python @property def filesystem() -> "AsyncSandboxFilesystem" ``` Get filesystem operations interface #### expose\_port ```python async def expose_port(port: int) -> ExposedPort ``` Expose a port to external connections via TCP proxy asynchronously. #### unexpose\_port ```python async def unexpose_port() -> None ``` Unexpose a port from external connections asynchronously. #### launch\_process ```python async def launch_process(cmd: str, cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None) -> str ``` Launch a background process in the sandbox asynchronously. #### kill\_process ```python async def kill_process(process_id: str) -> None ``` Kill a background process by its ID asynchronously. #### list\_processes ```python async def list_processes() -> List[ProcessInfo] ``` List all background processes asynchronously. #### kill\_all\_processes ```python async def kill_all_processes() -> int ``` Kill all running background processes asynchronously. #### update\_lifecycle ```python async def update_lifecycle( delete_after_delay: Optional[int] = None, delete_after_inactivity: Optional[int] = None) -> None ``` Update the sandbox's life cycle settings asynchronously. #### update\_network\_policy ```python async def update_network_policy( block_network: bool = False, outbound_allowlist: Optional[List[str]] = None) -> None ``` Update the sandbox's network policy asynchronously. Warning: applying a new network policy triggers a redeployment of the sandbox service. The sandbox is restarted and any in-memory or non-persisted state is lost. This method does not wait for the redeployment to finish; it repoints the sandbox at the new deployment and clears cached connection state, so call wait_ready() afterwards to block until the replacement deployment is healthy before issuing further operations. See Sandbox.update_network_policy for full documentation. **Raises**: - `EgressPolicyError` - If both block_network and outbound_allowlist are passed, or an allowlist entry is not a valid IP address or CIDR - `SandboxError` - If updating the network policy fails #### \_\_aenter\_\_ ```python async def __aenter__() -> "AsyncSandbox" ``` Async context manager entry - returns self. #### \_\_aexit\_\_ ```python async def __aexit__(exc_type, exc_val, exc_tb) -> None ``` Async context manager exit - automatically deletes the sandbox. # koyeb.sandbox.spec SandboxSpec: the create vocabulary for Koyeb sandboxes. One definition of a sandbox deployment — env/secret injection, mesh tri-state, scale-to-zero sleep, ports/routes, snapshot branches. Every create flow (sync and async, Sandbox and ServicePool) builds one spec and consumes its payloads, so the decision logic lives here exactly once. #### build\_env\_vars ```python def build_env_vars(env: Optional[Dict[str, Any]]) -> List[DeploymentEnv] ``` Build environment variables list from dictionary. **Arguments**: - `env` - Dictionary of environment variables. Values can be plain strings or ``Secret`` instances. A ``Secret`` value is rendered as ``"{{ secret. }}"`` so the Koyeb API substitutes the secret value at deploy time. **Returns**: List of DeploymentEnv objects #### build\_config\_files ```python def build_config_files( config_files: Optional[Dict[str, Any]]) -> List[ConfigFile] ``` Build config files list from dictionary. **Arguments**: - `config_files` - Dictionary mapping file paths to file contents. Values can be plain strings (default permissions 0644) or ``ConfigFile`` instances (custom permissions). The dict key is always used as the file path. **Returns**: List of ConfigFile objects #### create\_docker\_source ```python def create_docker_source(image: str, privileged: Optional[bool] = None, image_registry_secret: Optional[str] = None, entrypoint: Optional[List[str]] = None, command: Optional[str] = None, args: Optional[List[str]] = None) -> DockerSource ``` Create Docker source configuration. **Arguments**: - `image` - Docker image name - `privileged` - If True, run the container in privileged mode (default: None/False) - `image_registry_secret` - Name of the secret containing registry credentials for pulling private images - `entrypoint` - Override the default entrypoint of the Docker image - `command` - Override the default command of the Docker image - `args` - Arguments to pass to the command **Returns**: DockerSource object #### create\_koyeb\_sandbox\_ports ```python def create_koyeb_sandbox_ports(protocol: str = "http") -> List[DeploymentPort] ``` Create port configuration for koyeb/sandbox image. Creates two ports: - Port 3030 exposed on HTTP, mounted on /koyeb-sandbox/ - Port 3031 exposed with the specified protocol, mounted on / **Arguments**: - `protocol` - Protocol to use for port 3031 ("http" or "http2"), defaults to "http" **Returns**: List of DeploymentPort objects configured for koyeb/sandbox #### create\_koyeb\_sandbox\_proxy\_ports ```python def create_koyeb_sandbox_proxy_ports() -> List[DeploymentProxyPort] ``` Create TCP proxy port configuration for koyeb/sandbox image. Creates proxy port for direct TCP access: - Port 3031 exposed via TCP proxy **Returns**: List of DeploymentProxyPort objects configured for TCP proxy access #### create\_koyeb\_sandbox\_routes ```python def create_koyeb_sandbox_routes() -> List[DeploymentRoute] ``` Create route configuration for koyeb/sandbox image to make it publicly accessible. Creates two routes: - Port 3030 accessible at /koyeb-sandbox/ - Port 3031 accessible at / **Returns**: List of DeploymentRoute objects configured for koyeb/sandbox #### create\_deployment\_definition ```python def create_deployment_definition( name: str, docker_source: DockerSource, env_vars: List[DeploymentEnv], instance_type: str, definition_type: DeploymentDefinitionType = DeploymentDefinitionType. SANDBOX, ports: Optional[List[DeploymentPort]] = None, exposed_port_protocol: Optional[str] = None, region: Optional[str] = None, routes: Optional[List[DeploymentRoute]] = None, idle_timeout: int = 300, enable_tcp_proxy: bool = False, _experimental_enable_light_sleep: bool = False, _experimental_deep_sleep_value: int = 3900, enable_mesh: Optional[bool] = None, config_files: Optional[List[ConfigFile]] = None, network_policy: Optional[NetworkPolicy] = None ) -> DeploymentDefinition ``` Create deployment definition for a sandbox service. **Arguments**: - `name` - Service name - `docker_source` - Docker configuration - `env_vars` - Environment variables - `instance_type` - Instance type - `definition_type` - Deployment definition type. SANDBOX (the default) keeps the sandbox auto-wiring (ports 3030/3031 and the sandbox routes); every other type carries only caller-supplied ports/routes. - `ports` - Caller-supplied ports (non-SANDBOX definitions); SANDBOX always wires its own 3030/3031 pair. - `exposed_port_protocol` - Protocol to expose ports with ("http" or "http2"). If None, defaults to "http". If provided, must be one of "http" or "http2". - `region` - Region to deploy to. Defaults to KOYEB_REGION env var, or "na" if not set. - `routes` - List of routes for public access - `idle_timeout` - Number of seconds to wait before sleeping the instance if it receives no traffic - `enable_tcp_proxy` - If True, enables TCP proxy for direct TCP access to port 3031 - `_experimental_enable_light_sleep` - If True, uses light sleep when reaching idle_timeout. Light Sleep reduces cold starts to ~200ms. After scaling to zero, the service stays in Light Sleep for idle_timeout seconds before going into Deep Sleep. - `_experimental_deep_sleep_value` - Number of seconds for deep sleep when light sleep is enabled (default: 3900). Only used if _experimental_enable_light_sleep is True. Ignored otherwise. - `enable_mesh` - Mesh tri-state: None (default) = auto, True = enabled, False = disabled - `network_policy` - Optional network policy restricting egress traffic **Returns**: DeploymentDefinition object ## SandboxSpec Objects ```python @dataclass class SandboxSpec() ``` The single definition of a sandbox deployment. ``definition_type`` defaults to SANDBOX, which keeps the sandbox auto-wiring; pool flows set WEB/WORKER and carry their own ports and routes. Invalid egress or port protocol fails at construction, before any API call. Sandbox flows call apply_sandbox_secret() before deployment_definition(): the secret rides the env. Pool flows never inject one — the platform mints the executor secret. #### apply\_sandbox\_secret ```python def apply_sandbox_secret(sandbox_secret: Optional[str] = None) -> str ``` Generate when missing, inject into env, return the secret. #### app\_payload ```python def app_payload() -> Dict[str, Any] ``` CreateApp payload for the app a create call owns. #### deployment\_definition ```python def deployment_definition() -> DeploymentDefinition ``` The deployment definition; the sync model is the wire truth. #### deployment\_definition\_dict ```python def deployment_definition_dict() -> Dict[str, Any] ``` Wire-format definition; both model flavors coerce this dict. #### service\_life\_cycle ```python def service_life_cycle() -> Dict[str, Any] ``` ServiceLifeCycle payload. #### create\_service\_payload ```python def create_service_payload(app_id: str) -> Dict[str, Any] ``` CreateService payload. FULL snapshots omit the definition (the API infers it); every other shape pins one. # koyeb.sandbox.sync The pure diff engine behind filesystem.sync(). sync() is one-way like ``rsync -r`` without deltas: list both sides (a local walk against GET /files/list NDJSON), diff on path/type/size/mtime (+sha256 with checksum=True), and send the changed set as ~50 MiB tar batches through /files/archive. This module holds the decisions — walking, matching, diffing, planning — with no executor I/O, so every rule is testable against plain data and tmpdir trees. The wire shape on both sides is the executor's FileEntry: ``path`` (relative, /-separated), ``type`` (file|dir|symlink|other), ``size``, ``mode`` (4-digit octal permission bits), ``mtime`` (RFC 3339 UTC with nanoseconds). Exclude patterns follow the executor's archive-route semantics exactly — Go's path.Match, tried against the relative path and every /-separated suffix of it — so the local walk and the remote archive agree on what is in the tree. #### path\_match ```python def path_match(pattern: str, name: str) -> bool ``` Go's path.Match: '*', '?' and [...] never cross the '/' separator. #### excluded ```python def excluded(rel: str, patterns: Sequence[str]) -> bool ``` The executor's exclude rule: pattern against rel and every suffix. A directory that matches is pruned whole by the walker, so its descendants never reach this test — matching the archive route, which answers SkipDir at the same point. #### path\_excluded ```python def path_excluded(path: str, patterns: Sequence[str]) -> bool ``` A path, or any directory prefix of it, matches a pattern. The walker prunes a matching directory whole, so an entry under one is effectively excluded even when its own path does not match. #### format\_mtime ```python def format_mtime(ns: int) -> str ``` Nanoseconds since the epoch as the executor formats mtime. #### mtime\_seconds ```python def mtime_seconds(mtime: str) -> int ``` An RFC 3339 mtime as whole seconds since the epoch (floored). #### walk\_local ```python def walk_local(root: str, exclude: Sequence[str] = ()) -> List[Dict[str, Any]] ``` A local tree as FileEntry dicts, mirroring GET /files/list. Paths are relative to root and /-separated; the root itself is not an entry. Symlinks are listed, not followed (like the executor's walk), special files are skipped, and an excluded directory is pruned whole. ## SyncDiff Objects ```python @dataclass class SyncDiff() ``` What sync() must do with one pair of trees, before any transfer. to_transfer holds source entries (walk order) to copy; deletes holds destination entries absent from the source; skipped counts entries examined and left alone; bytes is the content bytes to move. #### diff ```python def diff( local_entries: Iterable[Dict[str, Any]], remote_entries: Iterable[Dict[str, Any]], *, delete: bool = False, local_hash: Optional[Callable[[str], str]] = None, remote_hash: Optional[Callable[[str], Optional[str]]] = None) -> SyncDiff ``` Diff two FileEntry trees and plan a one-way copy. An entry is unchanged when type, size and mtime (whole seconds) match on both sides. With hashing callables, files that pass that test are compared by sha256 too (checksum=True); a remote hash of None can't prove a change and skips. Unreadable remote entries (the ``error`` field) and unarchivable types (``other``) are never transfer candidates. #### hash\_candidates ```python def hash_candidates(source_entries: Iterable[Dict[str, Any]], dest_entries: Iterable[Dict[str, Any]]) -> List[str] ``` Paths that only a sha256 comparison can settle. Files present on both sides, matching on type, size and mtime: the candidates checksum=True must hash. The caller prefetches the executor-side digests for these in one pass (async has no other way to feed the pure, synchronous diff). #### plan\_batches ```python def plan_batches( entries: Sequence[Dict[str, Any]], part_size: int ) -> Tuple[List[List[Dict[str, Any]]], List[Dict[str, Any]]] ``` Cut the changed set into tar batches and oversized files. Batches accumulate raw file content up to part_size (~50 MiB): a file that would cross the boundary starts the next batch, so no file is ever split across archives. Files larger than one part go through upload_file/download_file instead. Directories and symlinks ride the next batch (their wire size is a header); a set of only those still produces one batch. #### remote\_join ```python def remote_join(remote: str, rel: str) -> str ``` A remote path for a relative entry path (remote paths are POSIX). #### join\_local ```python def join_local(root: str, rel: str) -> str ``` A local path for a relative entry path, on any platform. Paths come from the remote side on pull, so they get the archive member check, and a symlink among the parents under root is refused: writing through it would land outside root. #### prune\_descendants ```python def prune_descendants(paths: Sequence[str]) -> List[str] ``` Topmost paths only: deleting a directory takes its descendants. Input order is irrelevant; the result is sorted. A descendant of a kept path is already covered by its parent's recursive delete, and deleting it separately would just miss (it is already gone). #### relative\_remote ```python def relative_remote(local: str) -> str ``` The remote path used when remote=None: local's relative form. A relative local path is kept as-is (resolved by the executor against the sandbox workdir); an absolute one contributes its basename, rsync-style. #### build\_archive ```python def build_archive(root: str, entries: Sequence[Dict[str, Any]], dest: str) -> None ``` Write the changed entries as a gzip'd tar spooled to dest. Members mirror the executor's archive: paths relative and /-separated, modes and whole-second mtimes kept, symlinks as links. #### clean\_path ```python def clean_path(name: str) -> str ``` A relative path safe to write under the destination, or ValueError. The same refusal the executor applies to archives it extracts: absolute paths and .. escapes never touch the filesystem. #### open\_nofollow ```python def open_nofollow(path: str) -> BinaryIO ``` Open path for writing, refusing to follow a symlink at path. #### extract\_archive ```python def extract_archive(archive_path: str, dest: str, keep: Optional[Set[str]] = None) -> List[str] ``` Extract a spooled archive into dest, mirroring the executor. Missing parents are created; members in the way are replaced; directory modes and mtimes are applied after the contents (writing into a directory bumps its mtime, and a restrictive mode applied early would lock the contents out). With keep, only those members are extracted — the pull side's changed set. Returns the member paths extracted. # koyeb.sandbox.control\_plane The control-plane seam: the narrow interface between the sandbox layer and the Koyeb API. Two adapters share the orchestration above them — the generated koyeb.api (sync) and koyeb.api_async (async) clients — so the sandbox twins never touch model flavors again: neutral info types come out, payload dicts go in. Errors map to SandboxError exactly where the orchestration contract demands it (service lookup); raw ApiException propagates where callers clean up (create/delete/update). ## AppInfo Objects ```python @dataclass(frozen=True) class AppInfo() ``` Neutral app summary. ## ServiceInfo Objects ```python @dataclass(frozen=True) class ServiceInfo() ``` Neutral service summary. ## DeploymentInfo Objects ```python @dataclass(frozen=True) class DeploymentInfo() ``` Neutral deployment summary. status stays raw (enum or string) for classify_deployment_status; env is flattened for SANDBOX_SECRET extraction. The definition dict is its own seam op (deployment_definition) so wait-polling paths never pay for serialization. ## SyncControlPlane Objects ```python class SyncControlPlane() ``` Control-plane adapter over the generated koyeb.api clients. ## AsyncControlPlane Objects ```python class AsyncControlPlane() ``` Control-plane adapter over the generated koyeb.api_async clients. # koyeb.sandbox.exec Command execution utilities for Koyeb Sandbox instances Using SandboxClient HTTP API ## CommandStatus Objects ```python class CommandStatus(str, Enum) ``` Command execution status ## CommandResult Objects ```python @dataclass class CommandResult() ``` Result of a command execution using Koyeb API models #### success ```python @property def success() -> bool ``` Check if command executed successfully #### output ```python @property def output() -> str ``` Get combined stdout and stderr output ## SandboxCommandError Objects ```python class SandboxCommandError(SandboxError) ``` Raised when a sandbox command fails (opt-in via raise_on_error). ## \_EventFold Objects ```python class _EventFold() ``` Folds executor stream events into a CommandResult. The sync and async exec twins differ only in how events are pulled; this class owns what every event means. The executor sends output one line per event, without its line ending. Buffered stdout/stderr put it back so they match what /run returns: the event's "eol" when the executor sends one, a newline otherwise. Without "eol", output that doesn't end with a newline gets one appended. Callbacks receive "data" as sent, without the line ending. #### feed ```python def feed(event: Dict[str, Any]) -> Optional[CommandResult] ``` Consume one event; returns a result only for a failed start. ## SandboxExecutor Objects ```python class SandboxExecutor() ``` Synchronous command execution interface for Koyeb Sandbox instances. Bound to a specific sandbox instance. For async usage, use AsyncSandboxExecutor instead. #### \_\_call\_\_ ```python def __call__(command: str, cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None, timeout: Optional[int] = 300, on_stdout: Optional[Callable[[str], None]] = None, on_stderr: Optional[Callable[[str], None]] = None, stream: bool = True, raise_on_error: bool = False) -> CommandResult ``` Execute a command in a shell synchronously. Supports streaming output via callbacks. With stream=False the output comes in one response, which the sandbox gateway cuts with a 504 after 5 minutes without data: stream commands that can run longer. A non-streaming command is not re-sent on a server error, since it may have run already. **Arguments**: - `command` - Command to execute as a string (e.g., "python -c 'print(2+2)'") - `cwd` - Working directory for the command - `env` - Environment variables for the command - `timeout` - Total time budget for the command, in seconds (default: 300). When it runs out, SandboxTimeoutError is raised and the connection to the executor is closed, whether or not the command streams output. None sets no limit; with stream=False the gateway still ends the command after 5 minutes without data. When streaming, the budget is checked as output or a keepalive (every 10 s) arrives, so a silent command can overrun it by up to 10 s; AsyncSandboxExecutor enforces it on time. - `on_stdout` - Optional callback called with each stdout line, without its line ending. When a callback is set, output is not buffered in the result. - `on_stderr` - Optional callback called with each stderr line, without its line ending - `stream` - Run through /run_streaming (default) instead of /run. stdout/stderr are the same either way, except that output not ending with a newline gets one appended when streamed, unless the executor sends each line's "eol" **Returns**: - `CommandResult` - Result of the command execution **Example**: ```python # Synchronous execution result = sandbox.exec("echo hello") # With streaming callbacks result = sandbox.exec( "echo hello; sleep 1; echo world", on_stdout=lambda data: print(f"OUT: {data}"), on_stderr=lambda data: print(f"ERR: {data}"), ) ``` ## AsyncSandboxExecutor Objects ```python class AsyncSandboxExecutor(SandboxExecutor) ``` Async command execution interface for Koyeb Sandbox instances. Bound to a specific sandbox instance. Inherits from SandboxExecutor and provides async command execution using native async I/O via AsyncSandboxClient. #### \_\_call\_\_ ```python async def __call__(command: str, cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None, timeout: Optional[int] = 300, on_stdout: Optional[Callable[[str], None]] = None, on_stderr: Optional[Callable[[str], None]] = None, stream: bool = True, raise_on_error: bool = False) -> CommandResult ``` Execute a command in a shell asynchronously. Supports streaming output via callbacks. With stream=False the output comes in one response, which the sandbox gateway cuts with a 504 after 5 minutes without data: stream commands that can run longer. A non-streaming command is not re-sent on a server error, since it may have run already. **Arguments**: - `command` - Command to execute as a string (e.g., "python -c 'print(2+2)'") - `cwd` - Working directory for the command - `env` - Environment variables for the command - `timeout` - Total time budget for the command, in seconds (default: 300). When it runs out, SandboxTimeoutError is raised and the connection to the executor is closed, whether or not the command streams output. None sets no limit; with stream=False the gateway still ends the command after 5 minutes without data. - `on_stdout` - Optional callback called with each stdout line, without its line ending. When a callback is set, output is not buffered in the result. - `on_stderr` - Optional callback called with each stderr line, without its line ending - `stream` - Run through /run_streaming (default) instead of /run. stdout/stderr are the same either way, except that output not ending with a newline gets one appended when streamed, unless the executor sends each line's "eol" **Returns**: - `CommandResult` - Result of the command execution **Example**: ```python # Async execution result = await sandbox.exec("echo hello") # With streaming callbacks result = await sandbox.exec( "echo hello; sleep 1; echo world", on_stdout=lambda data: print(f"OUT: {data}"), on_stderr=lambda data: print(f"ERR: {data}"), ) ``` # koyeb.sandbox.executor\_client Sandbox Executor API Client Sync and async Python clients for interacting with the Sandbox Executor API. #### DEFAULT\_HTTP\_TIMEOUT seconds for HTTP requests ## ConnectionInfo Objects ```python @dataclass class ConnectionInfo() ``` Information needed to connect to a sandbox ## SandboxClient Objects ```python class SandboxClient() ``` Client for the Sandbox Executor API. #### \_\_init\_\_ ```python def __init__(conn_info: ConnectionInfo, timeout: float = DEFAULT_HTTP_TIMEOUT) ``` Initialize the Sandbox Client. **Arguments**: - `conn_info` - The parameters needed to connect to the sandbox - `timeout` - Request timeout in seconds (default: 30) #### close ```python def close() -> None ``` Close the HTTP client and release resources. #### \_\_enter\_\_ ```python def __enter__() ``` Context manager entry - returns self. #### \_\_exit\_\_ ```python def __exit__(exc_type, exc_val, exc_tb) -> None ``` Context manager exit - automatically closes the client. #### \_\_del\_\_ ```python def __del__() ``` Clean up client on deletion (fallback, not guaranteed to run). #### health ```python def health() -> Dict[str, str] ``` Check the health status of the server. Uses a short timeout and no retries since callers (wait_ready) already handle polling with backoff. **Returns**: Dict with status information **Raises**: - `httpx.HTTPStatusError` - If the health check fails - `httpx.TimeoutException` - If the health check times out #### run ```python def run(cmd: str, cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None, timeout: Optional[Union[float, httpx.Timeout]] = None) -> Dict[str, Any] ``` Execute a shell command in the sandbox. **Arguments**: - `cmd` - The shell command to execute - `cwd` - Optional working directory for command execution - `env` - Optional environment variables to set/override - `timeout` - Optional timeout in seconds for the request, or an httpx.Timeout (httpx.Timeout(None) for no limit). Defaults to the client's timeout **Returns**: Dict containing stdout, stderr, error (if any), and exit code #### run\_streaming ```python def run_streaming(cmd: str, cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None, timeout: Optional[float] = None, connect_timeout: float = 10.0) -> Iterator[Dict[str, Any]] ``` Execute a shell command in the sandbox and stream the output in real-time. This method uses Server-Sent Events (SSE) to stream command output line-by-line as it's produced. Use this for long-running commands where you want real-time output. For simple commands where buffered output is acceptable, use run() instead. **Arguments**: - `cmd` - The shell command to execute - `cwd` - Optional working directory for command execution - `env` - Optional environment variables to set/override - `timeout` - Optional time budget in seconds for the whole stream. Once it has passed, the stream is closed and SandboxTimeoutError is raised. Whether the command then stops is up to the executor. The budget is checked whenever a line arrives, keepalives (every 10 s) included, so the error can come up to one keepalive interval late. Without it, the stream runs until the command ends, and only a read silent for the client's timeout fails. - `connect_timeout` - Timeout in seconds for connecting to the executor, 10 by default and never more than timeout **Yields**: Dict events with the following types: - output events (as command produces output): - `{"stream"` - "stdout"|"stderr", "data": "line of output"} - complete event (when command finishes): - `{"code"` - , "error": false} - error event (if command fails to start): - `{"error"` - "error message"} **Raises**: - `SandboxTimeoutError` - If connecting, a read or the timeout budget times out **Example**: >>> client = SandboxClient("http://localhost:8080", "secret") >>> for event in client.run_streaming("echo 'Hello'; sleep 1; echo 'World'"): ... if "stream" in event: ... print(f"{event['stream']}: {event['data']}") ... elif "code" in event: ... print(f"Exit code: {event['code']}") #### write\_file ```python def write_file(path: str, content: str) -> Dict[str, Any] ``` Write content to a file. **Arguments**: - `path` - The file path to write to - `content` - The content to write **Returns**: Dict with success status and error if any #### read\_file ```python def read_file(path: str) -> Dict[str, Any] ``` Read content from a file. **Arguments**: - `path` - The file path to read from **Returns**: Dict with file content and error if any #### delete\_file ```python def delete_file(path: str) -> Dict[str, Any] ``` Delete a file. **Arguments**: - `path` - The file path to delete **Returns**: Dict with success status and error if any #### make\_dir ```python def make_dir(path: str) -> Dict[str, Any] ``` Create a directory (including parent directories). **Arguments**: - `path` - The directory path to create **Returns**: Dict with success status and error if any #### delete\_dir ```python def delete_dir(path: str) -> Dict[str, Any] ``` Recursively delete a directory and all its contents. **Arguments**: - `path` - The directory path to delete **Returns**: Dict with success status and error if any #### list\_dir ```python def list_dir(path: str) -> Dict[str, Any] ``` List the contents of a directory. **Arguments**: - `path` - The directory path to list **Returns**: Dict with entries list and error if any #### files\_stat ```python def files_stat(path: str, hash: Optional[str] = None) -> Dict[str, Any] ``` Stat a file on the streamed /files routes (executor v0.0.24+). **Arguments**: - `path` - The file path to stat - `hash` - "sha256" to add the file's digest to the reply (regular files only; the executor answers 400 otherwise) **Returns**: FileEntry dict: type (file|dir|symlink|other), size, mode (octal string), mtime (RFC 3339 UTC, nanoseconds), sha256 when asked #### files\_put ```python def files_put(path: str, content: Union[bytes, Iterator[bytes], BinaryIO], mode: Optional[str] = None, parents: bool = False, sha256: Optional[str] = None, timeout: Optional[float] = None) -> Dict[str, Any] ``` Stream content to a file through PUT /files (executor v0.0.24+). The executor writes to a temp file and renames it into place: readers never see a partial file and a failed upload leaves the destination as it was. The timeout bounds idle time (FILES_IDLE_TIMEOUT), not total transfer time. Not retried on network errors mid-stream: a streamed body cannot be replayed; only a connect-time failure (the request never left) is retried. **Arguments**: - `path` - The destination path - `content` - The bytes to write, streamed (constant memory) - `mode` - Octal permission string, e.g. "0644"; the existing destination's mode is kept when omitted - `parents` - Create missing parent directories - `sha256` - Expected content digest; the executor verifies it while streaming and fails with 400 on mismatch - `timeout` - Seconds without progress before the call fails (default FILES_IDLE_TIMEOUT) **Returns**: - `{"size"` - received bytes, "sha256": content digest} #### files\_read ```python def files_read(path: str, chunk_size: int = 65536, timeout: Optional[float] = None) -> Iterator[bytes] ``` Stream a file's bytes from GET /files (executor v0.0.24+). The executor serves Range requests; this stream is the whole file, chunk by chunk, constant memory on both sides. The timeout bounds idle time, not total download time. No retry: a broken stream is the fs layer's to resume. **Arguments**: - `path` - The file path to read - `chunk_size` - Bytes per yielded chunk - `timeout` - Seconds without progress before the stream fails (default FILES_IDLE_TIMEOUT) **Yields**: File content chunks #### has\_files\_routes ```python def has_files_routes() -> bool ``` Whether this sandbox's executor serves the streamed /files routes. Probes once per handle with a body-less GET /files/stat: the legacy executor (pre-v0.0.24) has no such route and answers 404, the new one answers 400 ("path is required"). The result is cached for the client's lifetime, so every handle warns at most once. Never inferred from a failed transfer: an early 404 on a large PUT can surface as a Cloudflare 502 on Nomad. **Returns**: True if the streamed /files routes are available #### files\_list ```python def files_list(path: str, recursive: bool = False) -> Iterator[Dict[str, Any]] ``` Stream a directory listing from GET /files/list (executor v0.0.24+). One JSON entry per line, yielded as the walk goes: a large tree is never held in memory. An entry the executor could not read carries an "error" field and the listing goes on. The timeout bounds idle time, not total listing time. **Arguments**: - `path` - The directory to list - `recursive` - Walk into subdirectories (a flat listing skips them) **Yields**: FileEntry dicts: path (relative, /-separated), type, size, mode (octal string), mtime (RFC 3339 UTC, nanoseconds) #### files\_archive\_get ```python def files_archive_get( path: str, exclude: Sequence[str] = ()) -> Iterator[bytes] ``` Stream a directory as a gzip'd tar from GET /files/archive (executor v0.0.24+). The root itself is not an entry; symlinks are archived as links and special files are skipped. The timeout bounds idle time, not total archive time. **Arguments**: - `path` - The directory to archive - `exclude` - Glob patterns; a matching path (or any /-separated suffix of it) is left out, a matching directory whole **Yields**: The archive's gzip bytes, chunk by chunk #### files\_archive\_put ```python def files_archive_put( path: str, content: Union[bytes, Iterator[bytes], BinaryIO]) -> Dict[str, Any] ``` Extract a gzip'd tar into the directory at path (executor v0.0.24+). The executor creates the directory when missing and refuses members that escape it (absolute paths, '..', links leaving the root). Entries already extracted stay in place when the stream ends short. Not retried on network errors mid-stream: a streamed body cannot be replayed; only a connect-time failure (the request never left) is retried. **Arguments**: - `path` - The destination directory - `content` - The archive's gzip bytes, streamed (constant memory) **Returns**: - `{"files"` - extracted file count, "bytes": extracted file bytes} #### files\_upload\_open ```python def files_upload_open(path: str, size: int, mode: Optional[str] = None, sha256: Optional[str] = None, timeout: Optional[float] = None) -> Dict[str, Any] ``` Open a multipart upload session (executor v0.0.24+). A file too large for one request uploads as offset-addressed parts: the executor truncates a temp file to `size` up front, so parts land in any order, in parallel, and a retried part overwrites the same bytes. Sessions live in memory — an executor restart or an idle hour loses them, and the upload starts over. **Arguments**: - `path` - The destination path - `size` - The final size in bytes - `mode` - Octal permission string, e.g. "0644" (the existing destination's mode is kept when omitted) - `sha256` - Expected whole-file digest, checked once at complete - `timeout` - Seconds without progress before this call fails (default DEFAULT_HTTP_TIMEOUT — a control call) **Returns**: {"upload_id", "max_part_size"} — the cap for every part #### files\_upload\_part ```python def files_upload_part(upload_id: str, offset: int, content: bytes, sha256: Optional[str] = None, timeout: Optional[float] = None) -> None ``` Write one part at its offset (executor v0.0.24+). The timeout bounds idle time, not the part's total time. A part is idempotent at the executor (a WriteAt of the same bytes), so transient network errors retry — the bytes must be replayable: callers pass the part's bytes, never a consumed stream. **Arguments**: - `upload_id` - The session from files_upload_open - `offset` - The part's position in the final file - `content` - The part's bytes - `sha256` - The part's digest, verified while streaming - `timeout` - Seconds without progress before the part fails (default FILES_IDLE_TIMEOUT) #### files\_upload\_status ```python def files_upload_status(upload_id: str, timeout: Optional[float] = None) -> Dict[str, Any] ``` The ranges received so far (executor v0.0.24+): half-open [start, end) spans, sorted and coalesced, so a live session can resume by sending what is missing. **Arguments**: - `upload_id` - The session to inspect **Returns**: {"size", "ranges": [{"start", "end"}, ...]} #### files\_upload\_complete ```python def files_upload_complete(upload_id: str, timeout: Optional[float] = None) -> Dict[str, Any] ``` Check coverage and commit (executor v0.0.24+). A 409 carries the missing ranges in the error body — the session stays live, so the caller can fill the gaps and complete again. On success the temp file is fsynced and renamed onto the destination; the whole-file sha256 from files_upload_open is checked here. **Arguments**: - `upload_id` - The session to complete **Returns**: {"size", "sha256"?} #### files\_upload\_abort ```python def files_upload_abort(upload_id: str, timeout: Optional[float] = None) -> None ``` Abort the session and remove its temp file (executor v0.0.24+). **Arguments**: - `upload_id` - The session to abort - `timeout` - Seconds without progress before this call fails (default DEFAULT_HTTP_TIMEOUT — a control call) #### bind\_port ```python def bind_port(port: int) -> Dict[str, Any] ``` Bind a port to the TCP proxy for external access. Configures the TCP proxy to forward traffic to the specified port inside the sandbox. This allows you to expose services running inside the sandbox to external connections. **Arguments**: - `port` - The port number to bind to (must be a valid port number) **Returns**: Dict with success status, message, and port information **Notes**: - Only one port can be bound at a time - Binding a new port will override the previous binding - The port must be available and accessible within the sandbox environment #### unbind\_port ```python def unbind_port(port: Optional[int] = None) -> Dict[str, Any] ``` Unbind a port from the TCP proxy. Removes the TCP proxy port binding, stopping traffic forwarding to the previously bound port. **Arguments**: - `port` - Optional port number to unbind. If provided, it must match the currently bound port. If not provided, any existing binding will be removed. **Returns**: Dict with success status and message **Notes**: - If a port is specified and doesn't match the currently bound port, the request will fail - After unbinding, the TCP proxy will no longer forward traffic #### start\_process ```python def start_process(cmd: str, cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None) -> Dict[str, Any] ``` Start a background process in the sandbox. Starts a long-running background process that continues executing even after the API call completes. Use this for servers, workers, or other long-running tasks. **Arguments**: - `cmd` - The shell command to execute as a background process - `cwd` - Optional working directory for the process - `env` - Optional environment variables to set/override for the process **Returns**: Dict with process id and success status: - id: The unique process ID (UUID string) - success: True if the process was started successfully **Example**: >>> client = SandboxClient("http://localhost:8080", "secret") >>> result = client.start_process("python -u server.py") >>> process_id = result["id"] >>> print(f"Started process: {process_id}") #### kill\_process ```python def kill_process(process_id: str) -> Dict[str, Any] ``` Kill a background process by its ID. Terminates a running background process. This sends a SIGTERM signal to the process, allowing it to clean up gracefully. If the process doesn't terminate within a timeout, it will be forcefully killed with SIGKILL. **Arguments**: - `process_id` - The unique process ID (UUID string) to kill **Returns**: Dict with success status and error message if any **Example**: >>> client = SandboxClient("http://localhost:8080", "secret") >>> result = client.kill_process("550e8400-e29b-41d4-a716-446655440000") >>> if result.get("success"): ... print("Process killed successfully") #### list\_processes ```python def list_processes() -> Dict[str, Any] ``` List all background processes. Returns information about all currently running and recently completed background processes. This includes both active processes and processes that have completed (which remain in memory until server restart). **Returns**: Dict with a list of processes: - processes: List of process objects, each containing: - id: Process ID (UUID string) - command: The command that was executed - status: Process status (e.g., "running", "completed") - pid: OS process ID (if running) - exit_code: Exit code (if completed) - started_at: ISO 8601 timestamp when process started - completed_at: ISO 8601 timestamp when process completed (if applicable) **Example**: >>> client = SandboxClient("http://localhost:8080", "secret") >>> result = client.list_processes() >>> for process in result.get("processes", []): ... print(f"{process['id']}: {process['command']} - {process['status']}") ## AsyncSandboxClient Objects ```python class AsyncSandboxClient() ``` Async client for the Sandbox Executor API using httpx. #### \_\_init\_\_ ```python def __init__(conn_info: ConnectionInfo, timeout: float = DEFAULT_HTTP_TIMEOUT) ``` Initialize the Async Sandbox Client. **Arguments**: - `conn_info` - The parameters needed to connect to the sandbox - `timeout` - Request timeout in seconds (default: 30) #### close ```python async def close() -> None ``` Close the HTTP client and release resources. #### \_\_aenter\_\_ ```python async def __aenter__() ``` Async context manager entry - returns self. #### \_\_aexit\_\_ ```python async def __aexit__(exc_type, exc_val, exc_tb) -> None ``` Async context manager exit - automatically closes the client. #### health ```python async def health() -> Dict[str, str] ``` Check the health status of the server. Uses a short timeout and no retries since callers (wait_ready) already handle polling with backoff. **Returns**: Dict with status information **Raises**: - `httpx.HTTPStatusError` - If the health check fails - `httpx.TimeoutException` - If the health check times out #### run ```python async def run( cmd: str, cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None, timeout: Optional[Union[float, httpx.Timeout]] = None) -> Dict[str, Any] ``` Execute a shell command in the sandbox. **Arguments**: - `cmd` - The shell command to execute - `cwd` - Optional working directory for command execution - `env` - Optional environment variables to set/override - `timeout` - Optional timeout in seconds for the request, or an httpx.Timeout (httpx.Timeout(None) for no limit). Defaults to the client's timeout **Returns**: Dict containing stdout, stderr, error (if any), and exit code #### run\_streaming ```python async def run_streaming( cmd: str, cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None, timeout: Optional[float] = None, connect_timeout: float = 10.0) -> AsyncIterator[Dict[str, Any]] ``` Execute a shell command in the sandbox and stream the output in real-time. This method uses Server-Sent Events (SSE) to stream command output line-by-line as it's produced. Use this for long-running commands where you want real-time output. For simple commands where buffered output is acceptable, use run() instead. **Arguments**: - `cmd` - The shell command to execute - `cwd` - Optional working directory for command execution - `env` - Optional environment variables to set/override - `timeout` - Optional time budget in seconds for the whole stream. Once it has passed, the stream is closed and SandboxTimeoutError is raised. Whether the command then stops is up to the executor. Without it, the stream runs until the command ends, and only a read silent for the client's timeout fails. - `connect_timeout` - Timeout in seconds for connecting to the executor, 10 by default and never more than timeout **Yields**: Dict events with the following types: - output events (as command produces output): - `{"stream"` - "stdout"|"stderr", "data": "line of output"} - complete event (when command finishes): - `{"code"` - , "error": false} - error event (if command fails to start): - `{"error"` - "error message"} **Raises**: - `SandboxTimeoutError` - If connecting, a read or the timeout budget times out **Example**: >>> client = AsyncSandboxClient("http://localhost:8080", "secret") >>> async for event in client.run_streaming("echo 'Hello'; sleep 1; echo 'World'"): ... if "stream" in event: ... print(f"{event['stream']}: {event['data']}") ... elif "code" in event: ... print(f"Exit code: {event['code']}") #### write\_file ```python async def write_file(path: str, content: str) -> Dict[str, Any] ``` Write content to a file. **Arguments**: - `path` - The file path to write to - `content` - The content to write **Returns**: Dict with success status and error if any #### read\_file ```python async def read_file(path: str) -> Dict[str, Any] ``` Read content from a file. **Arguments**: - `path` - The file path to read from **Returns**: Dict with file content and error if any #### delete\_file ```python async def delete_file(path: str) -> Dict[str, Any] ``` Delete a file. **Arguments**: - `path` - The file path to delete **Returns**: Dict with success status and error if any #### make\_dir ```python async def make_dir(path: str) -> Dict[str, Any] ``` Create a directory (including parent directories). **Arguments**: - `path` - The directory path to create **Returns**: Dict with success status and error if any #### delete\_dir ```python async def delete_dir(path: str) -> Dict[str, Any] ``` Recursively delete a directory and all its contents. **Arguments**: - `path` - The directory path to delete **Returns**: Dict with success status and error if any #### list\_dir ```python async def list_dir(path: str) -> Dict[str, Any] ``` List the contents of a directory. **Arguments**: - `path` - The directory path to list **Returns**: Dict with entries list and error if any #### files\_stat ```python async def files_stat(path: str, hash: Optional[str] = None) -> Dict[str, Any] ``` Stat a file on the streamed /files routes (executor v0.0.24+). **Arguments**: - `path` - The file path to stat - `hash` - "sha256" to add the file's digest to the reply (regular files only; the executor answers 400 otherwise) **Returns**: FileEntry dict: type (file|dir|symlink|other), size, mode (octal string), mtime (RFC 3339 UTC, nanoseconds), sha256 when asked #### files\_put ```python async def files_put(path: str, content: Union[bytes, AsyncIterator[bytes], Iterator[bytes], BinaryIO], mode: Optional[str] = None, parents: bool = False, sha256: Optional[str] = None, timeout: Optional[float] = None) -> Dict[str, Any] ``` Stream content to a file through PUT /files (executor v0.0.24+). The executor writes to a temp file and renames it into place: readers never see a partial file and a failed upload leaves the destination as it was. The timeout bounds idle time (FILES_IDLE_TIMEOUT), not total transfer time. Not retried on network errors mid-stream: a streamed body cannot be replayed; only a connect-time failure (the request never left) is retried. **Arguments**: - `path` - The destination path - `content` - The bytes to write, streamed (constant memory) - `mode` - Octal permission string, e.g. "0644"; the existing destination's mode is kept when omitted - `parents` - Create missing parent directories - `sha256` - Expected content digest; the executor verifies it while streaming and fails with 400 on mismatch - `timeout` - Seconds without progress before the call fails (default FILES_IDLE_TIMEOUT) **Returns**: - `{"size"` - received bytes, "sha256": content digest} #### files\_read ```python async def files_read(path: str, chunk_size: int = 65536, timeout: Optional[float] = None) -> AsyncIterator[bytes] ``` Stream a file's bytes from GET /files (executor v0.0.24+). The executor serves Range requests; this stream is the whole file, chunk by chunk, constant memory on both sides. The timeout bounds idle time, not total download time. No retry: a broken stream is the fs layer's to resume. **Arguments**: - `path` - The file path to read - `chunk_size` - Bytes per yielded chunk - `timeout` - Seconds without progress before the stream fails (default FILES_IDLE_TIMEOUT) **Yields**: File content chunks #### has\_files\_routes ```python async def has_files_routes() -> bool ``` Whether this sandbox's executor serves the streamed /files routes. Probes once per handle with a body-less GET /files/stat: the legacy executor (pre-v0.0.24) has no such route and answers 404, the new one answers 400 ("path is required"). The result is cached for the client's lifetime, so every handle warns at most once. Never inferred from a failed transfer: an early 404 on a large PUT can surface as a Cloudflare 502 on Nomad. **Returns**: True if the streamed /files routes are available #### files\_list ```python async def files_list(path: str, recursive: bool = False) -> AsyncIterator[Dict[str, Any]] ``` Stream a directory listing from GET /files/list (executor v0.0.24+). One JSON entry per line, yielded as the walk goes: a large tree is never held in memory. An entry the executor could not read carries an "error" field and the listing goes on. The timeout bounds idle time, not total listing time. **Arguments**: - `path` - The directory to list - `recursive` - Walk into subdirectories (a flat listing skips them) **Yields**: FileEntry dicts: path (relative, /-separated), type, size, mode (octal string), mtime (RFC 3339 UTC, nanoseconds) #### files\_archive\_get ```python async def files_archive_get( path: str, exclude: Sequence[str] = ()) -> AsyncIterator[bytes] ``` Stream a directory as a gzip'd tar from GET /files/archive (executor v0.0.24+). The root itself is not an entry; symlinks are archived as links and special files are skipped. The timeout bounds idle time, not total archive time. **Arguments**: - `path` - The directory to archive - `exclude` - Glob patterns; a matching path (or any /-separated suffix of it) is left out, a matching directory whole **Yields**: The archive's gzip bytes, chunk by chunk #### files\_archive\_put ```python async def files_archive_put( path: str, content: Union[bytes, AsyncIterator[bytes], Iterator[bytes], BinaryIO] ) -> Dict[str, Any] ``` Extract a gzip'd tar into the directory at path (executor v0.0.24+). The executor creates the directory when missing and refuses members that escape it (absolute paths, '..', links leaving the root). Entries already extracted stay in place when the stream ends short. Not retried on network errors mid-stream: a streamed body cannot be replayed; only a connect-time failure (the request never left) is retried. **Arguments**: - `path` - The destination directory - `content` - The archive's gzip bytes, streamed (constant memory) **Returns**: - `{"files"` - extracted file count, "bytes": extracted file bytes} #### files\_upload\_open ```python async def files_upload_open(path: str, size: int, mode: Optional[str] = None, sha256: Optional[str] = None, timeout: Optional[float] = None) -> Dict[str, Any] ``` Open a multipart upload session (executor v0.0.24+). A file too large for one request uploads as offset-addressed parts: the executor truncates a temp file to `size` up front, so parts land in any order, in parallel, and a retried part overwrites the same bytes. Sessions live in memory — an executor restart or an idle hour loses them, and the upload starts over. **Arguments**: - `path` - The destination path - `size` - The final size in bytes - `mode` - Octal permission string, e.g. "0644" (the existing destination's mode is kept when omitted) - `sha256` - Expected whole-file digest, checked once at complete - `timeout` - Seconds without progress before this call fails (default DEFAULT_HTTP_TIMEOUT — a control call) **Returns**: {"upload_id", "max_part_size"} — the cap for every part #### files\_upload\_part ```python async def files_upload_part(upload_id: str, offset: int, content: bytes, sha256: Optional[str] = None, timeout: Optional[float] = None) -> None ``` Write one part at its offset (executor v0.0.24+). The timeout bounds idle time, not the part's total time. A part is idempotent at the executor (a WriteAt of the same bytes), so transient network errors retry — the bytes must be replayable: callers pass the part's bytes, never a consumed stream. **Arguments**: - `upload_id` - The session from files_upload_open - `offset` - The part's position in the final file - `content` - The part's bytes - `sha256` - The part's digest, verified while streaming - `timeout` - Seconds without progress before the part fails (default FILES_IDLE_TIMEOUT) #### files\_upload\_status ```python async def files_upload_status(upload_id: str, timeout: Optional[float] = None ) -> Dict[str, Any] ``` The ranges received so far (executor v0.0.24+): half-open [start, end) spans, sorted and coalesced, so a live session can resume by sending what is missing. **Arguments**: - `upload_id` - The session to inspect **Returns**: {"size", "ranges": [{"start", "end"}, ...]} #### files\_upload\_complete ```python async def files_upload_complete(upload_id: str, timeout: Optional[float] = None ) -> Dict[str, Any] ``` Check coverage and commit (executor v0.0.24+). A 409 carries the missing ranges in the error body — the session stays live, so the caller can fill the gaps and complete again. On success the temp file is fsynced and renamed onto the destination; the whole-file sha256 from files_upload_open is checked here. **Arguments**: - `upload_id` - The session to complete **Returns**: {"size", "sha256"?} #### files\_upload\_abort ```python async def files_upload_abort(upload_id: str, timeout: Optional[float] = None) -> None ``` Abort the session and remove its temp file (executor v0.0.24+). **Arguments**: - `upload_id` - The session to abort - `timeout` - Seconds without progress before this call fails (default DEFAULT_HTTP_TIMEOUT — a control call) #### bind\_port ```python async def bind_port(port: int) -> Dict[str, Any] ``` Bind a port to the TCP proxy for external access. Configures the TCP proxy to forward traffic to the specified port inside the sandbox. This allows you to expose services running inside the sandbox to external connections. **Arguments**: - `port` - The port number to bind to (must be a valid port number) **Returns**: Dict with success status, message, and port information **Notes**: - Only one port can be bound at a time - Binding a new port will override the previous binding - The port must be available and accessible within the sandbox environment #### unbind\_port ```python async def unbind_port(port: Optional[int] = None) -> Dict[str, Any] ``` Unbind a port from the TCP proxy. Removes the TCP proxy port binding, stopping traffic forwarding to the previously bound port. **Arguments**: - `port` - Optional port number to unbind. If provided, it must match the currently bound port. If not provided, any existing binding will be removed. **Returns**: Dict with success status and message **Notes**: - If a port is specified and doesn't match the currently bound port, the request will fail - After unbinding, the TCP proxy will no longer forward traffic #### start\_process ```python async def start_process( cmd: str, cwd: Optional[str] = None, env: Optional[Dict[str, str]] = None) -> Dict[str, Any] ``` Start a background process in the sandbox. Starts a long-running background process that continues executing even after the API call completes. Use this for servers, workers, or other long-running tasks. **Arguments**: - `cmd` - The shell command to execute as a background process - `cwd` - Optional working directory for the process - `env` - Optional environment variables to set/override for the process **Returns**: Dict with process id and success status: - id: The unique process ID (UUID string) - success: True if the process was started successfully **Example**: >>> client = AsyncSandboxClient("http://localhost:8080", "secret") >>> result = await client.start_process("python -u server.py") >>> process_id = result["id"] >>> print(f"Started process: {process_id}") #### kill\_process ```python async def kill_process(process_id: str) -> Dict[str, Any] ``` Kill a background process by its ID. Terminates a running background process. This sends a SIGTERM signal to the process, allowing it to clean up gracefully. If the process doesn't terminate within a timeout, it will be forcefully killed with SIGKILL. **Arguments**: - `process_id` - The unique process ID (UUID string) to kill **Returns**: Dict with success status and error message if any **Example**: >>> client = AsyncSandboxClient("http://localhost:8080", "secret") >>> result = await client.kill_process("550e8400-e29b-41d4-a716-446655440000") >>> if result.get("success"): ... print("Process killed successfully") #### list\_processes ```python async def list_processes() -> Dict[str, Any] ``` List all background processes. Returns information about all currently running and recently completed background processes. This includes both active processes and processes that have completed (which remain in memory until server restart). **Returns**: Dict with a list of processes: - processes: List of process objects, each containing: - id: Process ID (UUID string) - command: The command that was executed - status: Process status (e.g., "running", "completed") - pid: OS process ID (if running) - exit_code: Exit code (if completed) - started_at: ISO 8601 timestamp when process started - completed_at: ISO 8601 timestamp when process completed (if applicable) **Example**: >>> client = AsyncSandboxClient("http://localhost:8080", "secret") >>> result = await client.list_processes() >>> for process in result.get("processes", []): ... print(f"{process['id']}: {process['command']} - {process['status']}") # koyeb.sandbox.filesystem Filesystem operations for Koyeb Sandbox instances Using SandboxClient HTTP API #### check\_error\_message ```python def check_error_message(error_msg: str, error_type: str) -> bool ``` Check if an error message matches a specific error type. Uses case-insensitive matching against known error patterns. **Arguments**: - `error_msg` - The error message to check - `error_type` - The type of error to check for (key in ERROR_MESSAGES) **Returns**: True if error message matches the error type #### escape\_shell\_arg ```python def escape_shell_arg(arg: str) -> str ``` Escape a shell argument for safe use in shell commands. **Arguments**: - `arg` - The argument to escape **Returns**: Properly escaped shell argument ## SandboxFilesystemError Objects ```python class SandboxFilesystemError(SandboxError) ``` Base exception for filesystem operations ## SandboxFileNotFoundError Objects ```python class SandboxFileNotFoundError(SandboxFilesystemError) ``` Raised when file or directory not found ## SandboxFileExistsError Objects ```python class SandboxFileExistsError(SandboxFilesystemError) ``` Raised when file already exists ## FileInfo Objects ```python @dataclass class FileInfo() ``` File information ## FileStat Objects ```python @dataclass class FileStat() ``` File metadata from the streamed /files/stat route (executor v0.0.24+). type is one of file|dir|symlink|other; mode is the octal permission string (e.g. "0644"); mtime is RFC 3339 UTC with nanoseconds. ## SandboxFilesystem Objects ```python class SandboxFilesystem() ``` Synchronous filesystem operations for Koyeb Sandbox instances. Using SandboxClient HTTP API. For async usage, use AsyncSandboxFilesystem instead. #### write\_file ```python def write_file(path: str, content: Union[str, bytes, BinaryIO, Iterable[bytes]], encoding: str = "utf-8", *, mode: Optional[str] = None) -> None ``` Write content to a file synchronously. On executors v0.0.24+ the content streams through PUT /files, binary-safe: any byte sequence lands on disk as-is. encoding="base64" decodes str and bytes content to the real bytes; BinaryIO and iterables stream as-is, ignoring it. Older executors are detected once per handle and keep the legacy JSON behavior — which cannot carry streamed content (BinaryIO, an iterable of chunks): that raises and names v0.0.24. **Arguments**: - `path` - Absolute path to the file - `content` - Content to write — string, bytes, a file object or an iterable of bytes chunks (the last two require executor v0.0.24+) - `encoding` - File encoding (default: "utf-8"). Use "base64" for binary data. - `mode` - Octal permission string, e.g. "0644" (streamed routes only; the legacy routes keep the destination's mode) #### read\_file ```python def read_file(path: str, encoding: Optional[str] = "utf-8") -> FileInfo ``` Read a file from the sandbox synchronously. On executors v0.0.24+ the bytes stream from GET /files, binary-safe: encoding=None returns the disk bytes, and encoding="base64" encodes the real bytes for transport. Older executors keep the legacy JSON behavior: encoding="base64" decodes the file's base64 text and returns bytes; encoding=None is not supported there and raises. **Arguments**: - `path` - Absolute path to the file - `encoding` - File encoding (default: "utf-8"). Streamed routes: None returns the disk bytes, "base64" encodes them. Legacy routes: "base64" decodes the file's base64 text; None raises. **Returns**: - `FileInfo` - Object with content (str or bytes) and encoding #### open\_read ```python def open_read(path: str) -> Iterator[bytes] ``` Stream a file's bytes from the sandbox, chunk by chunk. Constant memory on both sides (executor v0.0.24+). On legacy executors the file is read once as text and yielded as a single chunk — binary-safe streaming is not available there. **Arguments**: - `path` - Absolute path to the file **Yields**: File content chunks #### stat ```python def stat(path: str) -> FileStat ``` Stat a file on the sandbox (executor v0.0.24+). Legacy executors have no stat route: this raises. Size comes from the filesystem, never from a HEAD — size-0 pseudo-files (e.g. under /proc) carry no length but have content. **Arguments**: - `path` - Absolute path to the file **Returns**: FileStat with type (file|dir|symlink|other), size, mode (octal string) and mtime (RFC 3339 UTC, nanoseconds) #### mkdir ```python def mkdir(path: str) -> None ``` Create a directory synchronously. Note: Parent directories are always created automatically by the API. **Arguments**: - `path` - Absolute path to the directory #### list\_dir ```python def list_dir(path: str = ".") -> List[str] ``` List contents of a directory synchronously. **Arguments**: - `path` - Path to the directory (default: current directory) **Returns**: - `List[str]` - Names of files and directories within the specified path. #### delete\_file ```python def delete_file(path: str) -> None ``` Delete a file synchronously. **Arguments**: - `path` - Absolute path to the file #### delete\_dir ```python def delete_dir(path: str) -> None ``` Delete a directory synchronously. **Arguments**: - `path` - Absolute path to the directory #### rename\_file ```python def rename_file(old_path: str, new_path: str) -> None ``` Rename a file synchronously. **Arguments**: - `old_path` - Current file path - `new_path` - New file path #### move\_file ```python def move_file(source_path: str, destination_path: str) -> None ``` Move a file to a different directory synchronously. **Arguments**: - `source_path` - Current file path - `destination_path` - Destination path #### write\_files ```python def write_files(files: List[Dict[str, str]]) -> None ``` Write multiple files in a single operation synchronously. **Arguments**: - `files` - List of dictionaries, each with 'path', 'content', and optional 'encoding'. #### exists ```python def exists(path: str) -> bool ``` Check if file/directory exists synchronously #### is\_file ```python def is_file(path: str) -> bool ``` Check if path is a file synchronously #### is\_dir ```python def is_dir(path: str) -> bool ``` Check if path is a directory synchronously #### upload\_file ```python def upload_file(local_path: str, remote_path: str, encoding: str = "utf-8", *, progress: Optional[Callable[[int, int], None]] = None, timeout: Optional[float] = None, part_size: int = UPLOAD_PART_SIZE, concurrency: int = UPLOAD_CONCURRENCY) -> None ``` Upload a local file to the sandbox synchronously. On executors v0.0.24+ the file streams from disk through PUT /files — binary-safe, constant memory — with optional progress callbacks. A file larger than part_size uploads as a multipart session: up to `concurrency` parts in flight, each read from disk at its offset, per-part sha256, timed-out parts split into halves, and a complete that reports missing ranges fills them and completes again. Older executors keep the legacy JSON behavior (the encoding parameter applies there only). **Arguments**: - `local_path` - Path to the local file - `remote_path` - Destination path in the sandbox - `encoding` - Legacy executors only (default: "utf-8"); the streamed routes are binary-safe and ignore it - `progress` - Optional callback(done, total), called at most every 100 ms during the transfer plus a final call - `timeout` - Seconds without progress before the transfer's requests fail (default: the 60 s idle bound) - `part_size` - Bytes per multipart part (default 50 MiB, capped by the executor's max_part_size); a file at or below it takes the single streamed PUT - `concurrency` - Parts in flight for a multipart upload (default 4; memory holds at most part_size x concurrency) **Raises**: - `SandboxFileNotFoundError` - If local file doesn't exist #### download\_file ```python def download_file(remote_path: str, local_path: str, encoding: str = "utf-8", *, progress: Optional[Callable[[int, int], None]] = None, timeout: Optional[float] = None) -> None ``` Download a file from the sandbox to a local path synchronously. On executors v0.0.24+ the size comes from stat (never a HEAD), the bytes stream into .part and rename into place on success: a failed download leaves the destination exactly as it was. Older executors keep the legacy JSON behavior. **Arguments**: - `remote_path` - Path to the file in the sandbox - `local_path` - Destination path on the local filesystem - `encoding` - Legacy executors only (default: "utf-8"); the streamed routes are binary-safe and ignore it - `progress` - Optional callback(done, total), called at most every 100 ms during the transfer plus a final call - `timeout` - Seconds without progress before the transfer's stream fails (default: the 60 s idle bound) **Raises**: - `SandboxFileNotFoundError` - If remote file doesn't exist #### ls ```python def ls(path: str = ".") -> List[str] ``` List directory contents synchronously. **Arguments**: - `path` - Path to list **Returns**: List of file/directory names #### rm ```python def rm(path: str, recursive: bool = False) -> None ``` Remove file or directory synchronously. **Arguments**: - `path` - Path to remove - `recursive` - Remove recursively #### open ```python def open(path: str, mode: str = "r", encoding: str = "utf-8") -> SandboxFileIO ``` Open a file in the sandbox synchronously. **Arguments**: - `path` - Path to the file - `mode` - Open mode ('r', 'w', 'a', etc.) - `encoding` - File encoding (default: "utf-8"). Use "base64" for binary data. **Returns**: - `SandboxFileIO` - File handle #### sync ```python def sync(local: str, remote: Optional[str] = None, *, direction: str = "push", delete: bool = False, exclude: Sequence[str] = (), checksum: bool = False, dry_run: bool = False) -> Dict[str, int] ``` Sync a directory with the sandbox, one way like ``rsync -r``. Both sides are listed (a local walk against the executor's NDJSON listing) and diffed on path, type, size and mtime — whole seconds, like rsync's default; ``checksum=True`` adds a sha256 comparison for files that pass that test. On push, the changed set travels as ~50 MiB gzip'd tar batches through /files/archive; on pull, the remote tree's archive streams down and only the changed set is extracted. Files larger than one batch go through upload_file/download_file instead (multipart on executors v0.0.24+, resumable downloads), and a pull's archive leaves them out so their bytes travel once. Symlinks travel as links, modes are kept, owners are not. A pull never writes outside local: a path that leaves it, or that goes through a symlink, fails the sync. A no-op sync sends nothing: nothing is transferred or deleted; beyond the listing only ``checksum=True`` asks more — one sha256 stat per size-and-mtime-equal file. With ``delete=True`` the destination is pruned to match (a directory counts as one deletion); deletes ride the legacy routes, which every executor serves. ``dry_run=True`` computes the result without touching either side. **Arguments**: - `local` - Local directory path - `remote` - Destination path in the sandbox; relative paths resolve under the sandbox workdir. None uses local's relative form (its basename when absolute), rsync-style - `direction` - "push" (local → sandbox) or "pull" (sandbox → local) - `delete` - Remove destination entries absent from the source - `exclude` - Glob patterns; a matching path (or any /-separated suffix of it) is skipped, a matching directory whole - `checksum` - Compare sha256 for size-and-mtime-equal files - `dry_run` - Compute the plan only, transfer nothing **Returns**: {"uploaded"|"downloaded", "deleted", "skipped", "bytes"} **Raises**: - `SandboxFilesystemError` - On any failure, the filesystem taxonomy ## AsyncSandboxFilesystem Objects ```python class AsyncSandboxFilesystem(SandboxFilesystem) ``` Async filesystem operations for Koyeb Sandbox instances. Uses native async I/O via AsyncSandboxClient. #### write\_file ```python async def write_file(path: str, content: Union[str, bytes, BinaryIO, Iterable[bytes]], encoding: str = "utf-8", *, mode: Optional[str] = None) -> None ``` Write content to a file asynchronously. On executors v0.0.24+ the content streams through PUT /files, binary-safe: any byte sequence lands on disk as-is. encoding="base64" decodes str and bytes content to the real bytes; BinaryIO and iterables stream as-is, ignoring it. Older executors are detected once per handle and keep the legacy JSON behavior — which cannot carry streamed content (BinaryIO, an iterable of chunks): that raises and names v0.0.24. **Arguments**: - `path` - Absolute path to the file - `content` - Content to write — string, bytes, a file object or an iterable of bytes chunks (the last two require executor v0.0.24+) - `encoding` - File encoding (default: "utf-8"). Use "base64" for binary data. - `mode` - Octal permission string, e.g. "0644" (streamed routes only; the legacy routes keep the destination's mode) #### read\_file ```python async def read_file(path: str, encoding: Optional[str] = "utf-8") -> FileInfo ``` Read a file from the sandbox asynchronously. On executors v0.0.24+ the bytes stream from GET /files, binary-safe: encoding=None returns the disk bytes, and encoding="base64" encodes the real bytes for transport. Older executors keep the legacy JSON behavior: encoding="base64" decodes the file's base64 text and returns bytes; encoding=None is not supported there and raises. **Arguments**: - `path` - Absolute path to the file - `encoding` - File encoding (default: "utf-8"). Streamed routes: None returns the disk bytes, "base64" encodes them. Legacy routes: "base64" decodes the file's base64 text; None raises. **Returns**: - `FileInfo` - Object with content (str or bytes) and encoding #### open\_read ```python async def open_read(path: str) -> AsyncIterator[bytes] ``` Stream a file's bytes from the sandbox, chunk by chunk. Constant memory on both sides (executor v0.0.24+). On legacy executors the file is read once as text and yielded as a single chunk — binary-safe streaming is not available there. **Arguments**: - `path` - Absolute path to the file **Yields**: File content chunks #### stat ```python async def stat(path: str) -> FileStat ``` Stat a file on the sandbox (executor v0.0.24+). Legacy executors have no stat route: this raises. Size comes from the filesystem, never from a HEAD — size-0 pseudo-files (e.g. under /proc) carry no length but have content. **Arguments**: - `path` - Absolute path to the file **Returns**: FileStat with type (file|dir|symlink|other), size, mode (octal string) and mtime (RFC 3339 UTC, nanoseconds) #### mkdir ```python async def mkdir(path: str) -> None ``` Create a directory asynchronously. Note: Parent directories are always created automatically by the API. **Arguments**: - `path` - Absolute path to the directory #### list\_dir ```python async def list_dir(path: str = ".") -> List[str] ``` List contents of a directory asynchronously. **Arguments**: - `path` - Path to the directory (default: current directory) **Returns**: - `List[str]` - Names of files and directories within the specified path. #### delete\_file ```python async def delete_file(path: str) -> None ``` Delete a file asynchronously. **Arguments**: - `path` - Absolute path to the file #### delete\_dir ```python async def delete_dir(path: str) -> None ``` Delete a directory asynchronously. **Arguments**: - `path` - Absolute path to the directory #### rename\_file ```python async def rename_file(old_path: str, new_path: str) -> None ``` Rename a file asynchronously. **Arguments**: - `old_path` - Current file path - `new_path` - New file path #### move\_file ```python async def move_file(source_path: str, destination_path: str) -> None ``` Move a file to a different directory asynchronously. **Arguments**: - `source_path` - Current file path - `destination_path` - Destination path #### write\_files ```python async def write_files(files: List[Dict[str, str]]) -> None ``` Write multiple files in a single operation asynchronously. **Arguments**: - `files` - List of dictionaries, each with 'path', 'content', and optional 'encoding'. #### exists ```python async def exists(path: str) -> bool ``` Check if file/directory exists asynchronously #### is\_file ```python async def is_file(path: str) -> bool ``` Check if path is a file asynchronously #### is\_dir ```python async def is_dir(path: str) -> bool ``` Check if path is a directory asynchronously #### upload\_file ```python async def upload_file(local_path: str, remote_path: str, encoding: str = "utf-8", *, progress: Optional[Callable[[int, int], None]] = None, timeout: Optional[float] = None, part_size: int = UPLOAD_PART_SIZE, concurrency: int = UPLOAD_CONCURRENCY) -> None ``` Upload a local file to the sandbox asynchronously. On executors v0.0.24+ the file streams from disk through PUT /files — binary-safe, constant memory — with optional progress callbacks. A file larger than part_size uploads as a multipart session: up to `concurrency` parts in flight, each read from disk at its offset, per-part sha256, timed-out parts split into halves, and a complete that reports missing ranges fills them and completes again. Older executors keep the legacy JSON behavior (the encoding parameter applies there only). **Arguments**: - `local_path` - Path to the local file - `remote_path` - Destination path in the sandbox - `encoding` - Legacy executors only (default: "utf-8"); the streamed routes are binary-safe and ignore it - `progress` - Optional callback(done, total), called at most every 100 ms during the transfer plus a final call - `timeout` - Seconds without progress before the transfer's requests fail (default: the 60 s idle bound) - `part_size` - Bytes per multipart part (default 50 MiB, capped by the executor's max_part_size); a file at or below it takes the single streamed PUT - `concurrency` - Parts in flight for a multipart upload (default 4; memory holds at most part_size x concurrency) **Raises**: - `SandboxFileNotFoundError` - If local file doesn't exist #### download\_file ```python async def download_file(remote_path: str, local_path: str, encoding: str = "utf-8", *, progress: Optional[Callable[[int, int], None]] = None, timeout: Optional[float] = None) -> None ``` Download a file from the sandbox to a local path asynchronously. On executors v0.0.24+ the size comes from stat (never a HEAD), the bytes stream into .part and rename into place on success: a failed download leaves the destination exactly as it was. Older executors keep the legacy JSON behavior. **Arguments**: - `remote_path` - Path to the file in the sandbox - `local_path` - Destination path on the local filesystem - `encoding` - Legacy executors only (default: "utf-8"); the streamed routes are binary-safe and ignore it - `progress` - Optional callback(done, total), called at most every 100 ms during the transfer plus a final call - `timeout` - Seconds without progress before the transfer's stream fails (default: the 60 s idle bound) **Raises**: - `SandboxFileNotFoundError` - If remote file doesn't exist #### ls ```python async def ls(path: str = ".") -> List[str] ``` List directory contents asynchronously. **Arguments**: - `path` - Path to list **Returns**: List of file/directory names #### rm ```python async def rm(path: str, recursive: bool = False) -> None ``` Remove file or directory asynchronously. **Arguments**: - `path` - Path to remove - `recursive` - Remove recursively #### open ```python def open(path: str, mode: str = "r", encoding: str = "utf-8") -> AsyncSandboxFileIO ``` Open a file in the sandbox asynchronously. **Arguments**: - `path` - Path to the file - `mode` - Open mode ('r', 'w', 'a', etc.) - `encoding` - File encoding (default: "utf-8"). Use "base64" for binary data. **Returns**: - `AsyncSandboxFileIO` - Async file handle #### sync ```python async def sync(local: str, remote: Optional[str] = None, *, direction: str = "push", delete: bool = False, exclude: Sequence[str] = (), checksum: bool = False, dry_run: bool = False) -> Dict[str, int] ``` Sync a directory with the sandbox, one way like ``rsync -r``. Both sides are listed (a local walk against the executor's NDJSON listing) and diffed on path, type, size and mtime — whole seconds, like rsync's default; ``checksum=True`` adds a sha256 comparison for files that pass that test. On push, the changed set travels as ~50 MiB gzip'd tar batches through /files/archive; on pull, the remote tree's archive streams down and only the changed set is extracted. Files larger than one batch go through upload_file/download_file instead (multipart on executors v0.0.24+, resumable downloads), and a pull's archive leaves them out so their bytes travel once. Symlinks travel as links, modes are kept, owners are not. A pull never writes outside local: a path that leaves it, or that goes through a symlink, fails the sync. A no-op sync sends nothing: nothing is transferred or deleted; beyond the listing only ``checksum=True`` asks more — one sha256 stat per size-and-mtime-equal file. With ``delete=True`` the destination is pruned to match (a directory counts as one deletion); deletes ride the legacy routes, which every executor serves. ``dry_run=True`` computes the result without touching either side. **Arguments**: - `local` - Local directory path - `remote` - Destination path in the sandbox; relative paths resolve under the sandbox workdir. None uses local's relative form (its basename when absolute), rsync-style - `direction` - "push" (local → sandbox) or "pull" (sandbox → local) - `delete` - Remove destination entries absent from the source - `exclude` - Glob patterns; a matching path (or any /-separated suffix of it) is skipped, a matching directory whole - `checksum` - Compare sha256 for size-and-mtime-equal files - `dry_run` - Compute the plan only, transfer nothing **Returns**: {"uploaded"|"downloaded", "deleted", "skipped", "bytes"} **Raises**: - `SandboxFilesystemError` - On any failure, the filesystem taxonomy ## SandboxFileIO Objects ```python class SandboxFileIO() ``` Synchronous file I/O handle for sandbox files #### read ```python def read() -> Union[str, bytes] ``` Read file content synchronously #### write ```python def write(content: Union[str, bytes]) -> None ``` Write content to file synchronously #### close ```python def close() -> None ``` Close the file ## AsyncSandboxFileIO Objects ```python class AsyncSandboxFileIO() ``` Async file I/O handle for sandbox files #### read ```python async def read() -> Union[str, bytes] ``` Read file content asynchronously #### write ```python async def write(content: Union[str, bytes]) -> None ``` Write content to file asynchronously #### close ```python def close() -> None ``` Close the file # koyeb.sandbox.pool Koyeb service pools: pre-warmed sandbox pools and claims. Mirrors the JS SDK's service-pool.ts / claim.ts: a pool keeps ``size`` pre-warmed services ready; ``claim()`` hands one out idempotently (the same ``request_id`` returns the same claim), retrying transient failures (429/5xx) with linear backoff. Sync and async are fully mirrored. #### DEFAULT\_CLAIM\_RETRY\_DELAY seconds; linear: delay * attempt number #### DEFAULT\_CLAIM\_POLL\_INTERVAL seconds; the backoff starts at 0.1 ## ClaimResult Objects ```python @dataclass class ClaimResult() ``` A sandbox claimed from a service pool (``service_id`` is always set). The claimed sandbox is detached from the pool and owned by the caller. #### claim ```python def claim(pool_id: str, request_id: Optional[str] = None, api_token: Optional[str] = None, host: Optional[str] = None, max_attempts: int = DEFAULT_CLAIM_ATTEMPTS, retry_delay: float = DEFAULT_CLAIM_RETRY_DELAY) -> ClaimResult ``` Claim a sandbox from a service pool. On the warm path (``prewarmed=True``) the claimed sandbox is already running. On the cold path a sandbox service is created on demand: ``service_id`` is returned immediately and the sandbox becomes usable once the service is ready — see ``wait_claim_ready``. The claimed service is detached from the pool and owned by the caller: delete it like any other sandbox once you are done with it. Idempotent: the same ``(pool_id, request_id)`` pair always returns the same claim; ``request_id`` defaults to a generated UUID and is preserved across the SDK's internal retries. #### claim\_async ```python async def claim_async( pool_id: str, request_id: Optional[str] = None, api_token: Optional[str] = None, host: Optional[str] = None, max_attempts: int = DEFAULT_CLAIM_ATTEMPTS, retry_delay: float = DEFAULT_CLAIM_RETRY_DELAY) -> ClaimResult ``` Async twin of :func:`claim`. #### get\_claim ```python def get_claim(claim_id: str, api_token: Optional[str] = None, host: Optional[str] = None) -> PoolClaim ``` Fetch a claim's state (UNSPECIFIED, PENDING, FULFILLED, FAILED, RELEASED). #### get\_claim\_async ```python async def get_claim_async(claim_id: str, api_token: Optional[str] = None, host: Optional[str] = None) -> Any ``` Async twin of :func:`get_claim`. #### list\_claims ```python def list_claims(pool_id: str, status: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, api_token: Optional[str] = None, host: Optional[str] = None) -> List[PoolClaim] ``` List claims on a service pool, optionally filtered by status. #### list\_claims\_async ```python async def list_claims_async(pool_id: str, status: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, api_token: Optional[str] = None, host: Optional[str] = None) -> List[Any] ``` Async twin of :func:`list_claims`. #### wait\_claim\_ready ```python def wait_claim_ready(claim_or_service_id: Union[ClaimResult, str], timeout: float = DEFAULT_CLAIM_WAIT_TIMEOUT, poll_interval: float = DEFAULT_CLAIM_POLL_INTERVAL, api_token: Optional[str] = None, host: Optional[str] = None) -> bool ``` Poll Get Service until the claimed sandbox is ready. General service-health polling: returns True on ready, False on timeout, and raises :class:`ServiceTerminalStateError` on terminal states. Transient Get Service failures are treated as in-progress and retried until the timeout (they dominate while a cold claim provisions). Polls after 0.1s, then doubles the interval each time up to ``poll_interval``. #### wait\_claim\_ready\_async ```python async def wait_claim_ready_async( claim_or_service_id: Union[ClaimResult, str], timeout: float = DEFAULT_CLAIM_WAIT_TIMEOUT, poll_interval: float = DEFAULT_CLAIM_POLL_INTERVAL, api_token: Optional[str] = None, host: Optional[str] = None) -> bool ``` Async twin of :func:`wait_claim_ready`. ## ServicePool Objects ```python class ServicePool() ``` A Koyeb service pool keeping pre-warmed sandboxes ready to claim. #### create ```python @classmethod def create(cls, name: str, image: str = "koyeb/sandbox", size: int = DEFAULT_POOL_SIZE, instance_type: str = "micro", region: Optional[str] = None, env: Optional[dict] = None, config_files: Optional[dict] = None, type: str = "SANDBOX", entrypoint: Optional[List[str]] = None, command: Optional[str] = None, args: Optional[List[str]] = None, ports: Optional[List[Any]] = None, routes: Optional[List[Any]] = None, privileged: bool = False, registry_secret: Optional[str] = None, exposed_port_protocol: Optional[str] = None, enable_tcp_proxy: bool = False, idle_timeout: int = 300, _experimental_enable_light_sleep: bool = False, block_network: bool = False, outbound_allowlist: Optional[List[str]] = None, api_token: Optional[str] = None, host: Optional[str] = None) -> "ServicePool" ``` Create a pool of ``size`` pre-warmed services built from one definition. ``type`` selects the definition type: WEB, WORKER, or SANDBOX (the default). SANDBOX pools keep the sandbox auto-wiring (ports 3030/3031 and the sandbox routes); the platform mints their executor secret, and an explicit ``SANDBOX_SECRET`` in ``env`` wins over minting. WEB and WORKER pools carry exactly the declared ``ports`` and ``routes`` — no secret, no auto ports. The docker overrides (``entrypoint``, ``command``, ``args``) apply to every pool type. Mesh stays AUTO: there is no pool-level mesh option. #### list ```python @classmethod def list(cls, name: Optional[str] = None, status: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, api_token: Optional[str] = None, host: Optional[str] = None) -> List["ServicePool"] ``` List service pools, optionally filtered by name and status. The status filter takes the lowercase model value (`ready`, `provisioning`, `error` or `deleting`), not the uppercase enum name the reply carries; the API rejects anything else with a 400. #### update ```python def update(size: Optional[int] = None) -> "ServicePool" ``` Resize the pool; returns the updated pool. #### delete ```python def delete() -> None ``` Delete the pool (async server-side: it enters DELETING). #### refresh ```python def refresh() -> "ServicePool" ``` Re-fetch the pool's state (ready_count, status) in place. ## AsyncServicePool Objects ```python class AsyncServicePool() ``` Async twin of :class:`ServicePool`. #### list ```python @classmethod async def list(cls, name: Optional[str] = None, status: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, api_token: Optional[str] = None, host: Optional[str] = None) -> List["AsyncServicePool"] ``` List service pools, optionally filtered by name and status (async). The status filter takes the lowercase model value (`ready`, `provisioning`, `error` or `deleting`), not the uppercase enum name the reply carries; the API rejects anything else with a 400. #### update ```python async def update(size: Optional[int] = None) -> "AsyncServicePool" ``` Resize the pool; returns the updated pool. # koyeb.sandbox.snapshot Koyeb Sandbox Snapshot - Snapshot functionality for Koyeb sandboxes ## SnapshotType Objects ```python class SnapshotType(Enum) ``` Types of sandbox snapshots. ## SnapshotStatus Objects ```python class SnapshotStatus(Enum) ``` Status of a sandbox snapshot. ## Snapshot Objects ```python @dataclass class Snapshot() ``` Represents a sandbox snapshot resource. A snapshot captures the state of a sandbox at a specific point in time, including its filesystem and optionally running processes. Sandboxes can be spawned from snapshots to create pre-configured environments. #### get ```python @classmethod def get(cls, snapshot_id: str, api_token: Optional[str] = None, host: Optional[str] = None) -> Snapshot ``` Get a snapshot by ID. Uses the InstanceSnapshots API which is for sandbox/service instance snapshots. **Arguments**: - `snapshot_id` - The ID of the snapshot to retrieve - `api_token` - Koyeb API token (falls back to KOYEB_API_TOKEN env var) - `host` - Koyeb API host **Returns**: - `Snapshot` - The snapshot object **Raises**: - `SandboxError` - If snapshot cannot be retrieved #### list ```python @classmethod def list(cls, service_id: Optional[str] = None, name: Optional[str] = None, snapshot_type: Optional[SnapshotType] = None, status: Optional[SnapshotStatus] = None, limit: int = 50, offset: int = 0, api_token: Optional[str] = None, host: Optional[str] = None) -> List[Snapshot] ``` List snapshots with optional filters. Uses the InstanceSnapshots API which is for sandbox/service instance snapshots. **Arguments**: - `service_id` - Filter by service ID (applied to the returned page; the list endpoint has no service_id query param) - `name` - Filter by snapshot name - `snapshot_type` - Filter by snapshot type - `status` - Filter by snapshot status - `limit` - Maximum number of snapshots to return - `offset` - Offset for pagination - `api_token` - Koyeb API token - `host` - Koyeb API host **Returns**: List of Snapshot objects #### refresh ```python def refresh() -> None ``` Refresh snapshot state from the API. #### wait\_available ```python def wait_available(timeout: int = 600, poll_interval: float = 5.0) -> bool ``` Wait for snapshot to become available. **Arguments**: - `timeout` - Maximum time to wait in seconds - `poll_interval` - Time between status checks in seconds **Returns**: True if snapshot became available, False if timeout #### delete ```python def delete() -> bool ``` Delete this snapshot. Uses the InstanceSnapshots API which is for sandbox/service instance snapshots. **Returns**: True if deletion was successful #### spawn ```python def spawn(name: Optional[str] = None, wait_ready: bool = True, timeout: int = 300, **create_kwargs) -> Sandbox ``` Spawn a new sandbox from this snapshot. **Arguments**: - `name` - Name for the new sandbox - `wait_ready` - Whether to wait for sandbox to be ready - `timeout` - Timeout for sandbox creation in seconds - `**create_kwargs` - Additional arguments to pass to Sandbox.create() **Returns**: - `Sandbox` - A new sandbox instance initialized from this snapshot ## DeclarativeSnapshot Objects ```python class DeclarativeSnapshot() ``` Fluent builder for creating sandbox snapshots declaratively. This builder allows you to define a sandbox environment by: - Writing files - Copying local files/directories - Running setup commands - Setting environment variables Then builds a snapshot that can be used to spawn pre-configured sandboxes. #### \_\_init\_\_ ```python def __init__(name: str, image: str, workdir: Optional[str] = None, api_token: Optional[str] = None, host: Optional[str] = None, delete_builder: bool = True) ``` Initialize the declarative snapshot builder. **Arguments**: - `name` - Name for the template/builder - `image` - Docker image to use for the sandbox - `workdir` - Working directory in the sandbox - `api_token` - Koyeb API token - `host` - Koyeb API host - `delete_builder` - Whether to delete the builder sandbox after creating the snapshot (default: True) #### file ```python def file(path: str, content: str) -> DeclarativeSnapshot ``` Write a file to the sandbox during build. **Arguments**: - `path` - Path in the sandbox (e.g., "/workspace/requirements.txt") - `content` - File content as string **Returns**: self for method chaining #### copy ```python def copy(src: str, dst: str) -> DeclarativeSnapshot ``` Copy a local file or directory to the sandbox during build. **Arguments**: - `src` - Local source path (file or directory) - `dst` - Destination path in the sandbox **Returns**: self for method chaining #### run ```python def run(command: str, cwd: Optional[str] = None) -> DeclarativeSnapshot ``` Run a command during build. **Arguments**: - `command` - Command to execute - `cwd` - Working directory for the command **Returns**: self for method chaining #### build ```python def build(snapshot_name: Optional[str] = None) -> Snapshot ``` Build the snapshot by creating a temporary sandbox, applying all configurations, and creating a snapshot. The builder sandbox is automatically deleted after the snapshot is created. **Arguments**: - `snapshot_name` - Name for the snapshot (defaults to builder name) **Returns**: - `Snapshot` - The created snapshot #### get\_operations ```python def get_operations() -> List[str] ``` Get list of operations recorded during build. # koyeb.sandbox.errors The SDK error taxonomy: every failure the sandbox layer raises is a SandboxError subclass, so callers catch one family. ## SandboxError Objects ```python class SandboxError(Exception) ``` Base exception for sandbox operations ## MissingApiTokenError Objects ```python class MissingApiTokenError(SandboxError, ValueError) ``` Raised when no API token is provided and KOYEB_API_TOKEN is unset. Also inherits ValueError for back-compat with published 1.5.x callers that catch the old plain ValueError from the token gates. ## InvalidPortError Objects ```python class InvalidPortError(SandboxError, ValueError) ``` Raised when a port is not an integer in [MIN_PORT, MAX_PORT]. Also inherits ValueError for back-compat with published 1.5.x callers that catch the old plain ValueError from validate_port. ## NoSandboxSecretError Objects ```python class NoSandboxSecretError(SandboxError) ``` Raised when a sandbox deployment carries no SANDBOX_SECRET, so the executor connection cannot be established. ## SandboxTimeoutError Objects ```python class SandboxTimeoutError(SandboxError) ``` Raised when a sandbox operation times out ## SandboxDeploymentError Objects ```python class SandboxDeploymentError(SandboxError) ``` Raised when a sandbox deployment reaches a terminal state. Carries the sandbox name and the terminal status, so callers can branch (e.g. wake on SLEEPING) instead of parsing the message. ## SandboxRequestError Objects ```python class SandboxRequestError(SandboxError) ``` Raised when the sandbox executor returns a non-OK HTTP response. Carries the HTTP status code and response body. SandboxServiceError (HTTP 5xx) subclasses this, so `except SandboxRequestError` catches every executor HTTP failure — mirroring the JS SDK's SandboxRequestError. ## SandboxServiceError Objects ```python class SandboxServiceError(SandboxRequestError) ``` Raised when the sandbox executor returns an HTTP 5xx error ## EgressPolicyError Objects ```python class EgressPolicyError(SandboxError) ``` Raised when egress policy arguments are invalid or conflicting ## PoolClaimError Objects ```python class PoolClaimError(SandboxError) ``` Raised when claiming a sandbox from a service pool fails ## ServicePoolError Objects ```python class ServicePoolError(SandboxError) ``` Raised when a service pool operation fails ## ServiceTerminalStateError Objects ```python class ServiceTerminalStateError(SandboxError) ``` Raised when a service reaches a state that will never become ready # koyeb.sandbox.status Status classification for readiness polling, failing closed on unknown or terminal states. #### classify\_service\_status ```python def classify_service_status( status: Union[ServiceStatus, str]) -> StatusClassification ``` Classify a service status for readiness, failing closed. HEALTHY and DEGRADED are usable, STARTING and RESUMING are still in progress, and every other state — including unknown forward-compat values — is a terminal failure. Mirrors the JS SDK's classifyServiceStatus (src/claim.ts). #### classify\_deployment\_status ```python def classify_deployment_status( status: Union[DeploymentStatus, str]) -> StatusClassification ``` Classify a deployment status for readiness, failing closed. HEALTHY and DEGRADED are ready, the pre-ready states (PENDING, PROVISIONING, SCHEDULED, ALLOCATING, STARTING) are in progress, and every other state — including SLEEPING, STASHED, and unknown forward-compat values — is terminal: it will not become ready on its own during a wait. # koyeb.sandbox.clients Control-plane client bundles, their (token, host) caches, and the sandbox executor client factories. ## ApiClients Objects ```python @dataclass(frozen=True) class ApiClients() ``` Bundle of Koyeb API clients sharing a single underlying ApiClient. #### get\_api\_clients ```python def get_api_clients(api_token: Optional[str] = None, host: Optional[str] = None) -> ApiClients ``` Get configured API clients for Koyeb operations. Caches clients by (token, host) to reuse the underlying HTTP connection pool. **Arguments**: - `api_token` - Koyeb API token. If not provided, will try to get from KOYEB_API_TOKEN env var - `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com) **Returns**: ApiClients with apps, services, instances, catalog_instances, deployments, and secrets attributes **Raises**: - `ValueError` - If API token is not provided ## AsyncApiClients Objects ```python @dataclass(frozen=True) class AsyncApiClients() ``` Bundle of async Koyeb API clients sharing a single underlying AsyncApiClient. #### get\_async\_api\_clients ```python def get_async_api_clients(api_token: Optional[str] = None, host: Optional[str] = None) -> AsyncApiClients ``` Get configured async API clients for Koyeb operations. Caches clients by (token, host) to reuse the underlying HTTP connection pool. **Arguments**: - `api_token` - Koyeb API token. If not provided, will try to get from KOYEB_API_TOKEN env var - `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var **Returns**: AsyncApiClients with async API client instances **Raises**: - `ValueError` - If API token is not provided #### create\_sandbox\_client ```python def create_sandbox_client(conn_info: Optional["ConnectionInfo"], existing_client: Optional[Any] = None) -> Any ``` Create or return existing SandboxClient instance with validation. Helper function to create SandboxClient instances with consistent validation. Used by Sandbox, SandboxExecutor, and SandboxFilesystem to avoid duplication. **Arguments**: - `conn_info` - The information needed to connect to the sandbox executor API - `existing_client` - Existing client instance to return if not None **Returns**: - `SandboxClient` - Configured client instance **Raises**: - `SandboxError` - If sandbox URL or secret is not available #### create\_async\_sandbox\_client ```python def create_async_sandbox_client(conn_info: Optional["ConnectionInfo"], existing_client: Optional[Any] = None) -> Any ``` Create or return existing AsyncSandboxClient instance with validation. Helper function to create AsyncSandboxClient instances with consistent validation. Used by AsyncSandbox to avoid duplication. **Arguments**: - `conn_info` - The information needed to connect to the sandbox executor API - `existing_client` - Existing client instance to return if not None **Returns**: - `AsyncSandboxClient` - Configured async client instance **Raises**: - `SandboxError` - If sandbox URL or secret is not available # koyeb.sandbox.egress Outbound egress policy building and destination normalization. #### build\_network\_policy ```python def build_network_policy( block_network: bool = False, outbound_allowlist: Optional[List[str]] = None ) -> Optional[NetworkPolicy] ``` Build a NetworkPolicy from sandbox network policy arguments. **Arguments**: - `block_network` - If True, block all outbound network access - `outbound_allowlist` - List of IPs/CIDRs allowed as outbound destinations; all other outbound traffic is blocked. Bare IPs are normalized to /32 (IPv4) or /128 (IPv6). An empty list blocks all outbound traffic. **Returns**: NetworkPolicy, or None when both arguments are unset (block_network=False and outbound_allowlist=None) **Raises**: - `EgressPolicyError` - If both arguments are passed, or an allowlist entry is not a valid IP address or CIDR