# 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