Manager
DaimonManagerClient manages sandbox lifecycle against processd-sandbox-manager.
High-level client that talks to the processd-sandbox-manager HTTP API. Manages sandbox lifecycle — create, find-or-create, start, stop, delete.
DaimonManagerClient
DaimonManagerClient(base_url, *, access_token=None, timeout_s=30.0)Construct a manager client targeting the sandbox manager HTTP endpoint.
| Parameter | Type | Default | Description |
|---|---|---|---|
base_url | str | Scheduler (or manager) HTTP endpoint (e.g. http://127.0.0.1:18081). | |
access_token | str | None | None | Access token for X-Access-Token header. |
timeout_s | float | 30.0 | HTTP request timeout. |
async manager.health() -> bool
Check if the manager is reachable and healthy.
async manager.capacity() -> ManagerCapacityResult
Get the ready idle Pod count and the remaining active sandbox slots. available_now
is bounded by both the ready pool and any configured activity limit. When no
maxSandboxes limit is configured, max_sandboxes and remaining_slots are
None. The result also includes running_sandboxes, creating_sandboxes,
releasing_sandboxes (Pods terminating or awaiting cleanup),
pool.target, pool.ready, pool.pending, and a status of ready,
warming, pool_empty, at_limit, or over_limit.
capacity = await manager.capacity()
print(capacity.available_now, capacity.remaining_slots, capacity.pool.pending)async manager.create_sandbox() -> DaimonSandbox
Create a fresh sandbox workspace. The SDK waits for the Kubernetes Pod to reach
running; the manager API may initially return creating.
async manager.find_or_create_sandbox(*, labels, ttl_seconds=None) -> DaimonSandbox
Find a sandbox by labels or create one if none matches. Useful for thread-scoped sandbox reuse.
| Parameter | Type | Default | Description |
|---|---|---|---|
labels | dict[str, str] | Labels to match against existing sandboxes. | |
ttl_seconds | int | None | None | Time-to-live in seconds for the sandbox. |
sandbox = await manager.find_or_create_sandbox(
labels={"thread_id": "chat-123"},
ttl_seconds=3600,
)async manager.get_sandbox(sandbox_id) -> SandboxInfo
Get sandbox info by ID.
async manager.start_sandbox(sandbox_id) -> SandboxInfo
Start a stopped sandbox in a new Pod with a fresh workspace.
async manager.stop_sandbox(sandbox_id) -> SandboxInfo
Stop a running sandbox and destroy its Pod and workspace. The SDK waits until Kubernetes confirms the Pod has stopped.
async manager.delete_sandbox(sandbox_id) -> bool
Delete a sandbox and its workspace permanently. Returns False while the Pod
is still terminating (deleting), then True once the Pod and record are gone.
manager.sandbox(*, delete_on_exit=True) -> SandboxContext
Return an async context manager that creates, connects, and optionally deletes a sandbox.
async with manager.sandbox() as sandbox:
result = await sandbox.exec.bash("pwd")
print(result.display_text)DaimonSandbox
Wraps a sandbox info and its connected MCP client. Exposes the same namespaces as DaimonClient.
sandbox.info -> SandboxInfosandbox.id -> strsandbox.runtime -> RuntimeAPIsandbox.files -> FilesAPIsandbox.exec -> ExecAPIsandbox.web -> WebAPIsandbox.raw -> RawAPIsandbox.refresh() -> SandboxInfosandbox.start() -> SandboxInfosandbox.stop() -> SandboxInfosandbox.delete() -> None
SandboxContext
Async context manager returned by manager.sandbox(). Creates a sandbox on enter, connects the client, and optionally deletes on exit.