daimon-sdk

Typed async Python SDK for processd-mcp and processd-sandbox-manager.

daimon-sdk wraps the raw MCP tool surface exposed by processd-mcp and presents it as grouped Python APIs such as client.files.read() and client.exec.start_session(). The SDK keeps the monorepo's core project as the contract source of truth and focuses on:

• connection and token wiring
• manager sandbox lifecycle helpers
• typed request/response handling
• structured tool error mapping
• interactive session helpers
• compatibility tests against a real processd-mcp binary

Install

pip install daimon-sdk

For local development:

pip install -e ".[dev]"

Quickstart

With a sandbox manager:

import asyncio

from daimon_sdk import DaimonManagerClient


async def main() -> None:
    async with DaimonManagerClient("http://127.0.0.1:18080") as manager:
        async with manager.sandbox() as sandbox:
            runtime = await sandbox.runtime.get_context()
            print(runtime.base_workdir)

            result = await sandbox.exec.bash("python3 --version")
            print(result.stdout or result.stderr)


asyncio.run(main())

Using a processd scheduler

processd-scheduler is wire-compatible with the manager API, so use the same DaimonManagerClient and point base_url at any scheduler replica. No separate scheduler client is required:

async with DaimonManagerClient(
    "https://processd.example.com",
    access_token="cluster-control-token",
) as manager:
    sandbox = await manager.create_sandbox()
    print(sandbox.id)

Scheduler sandbox IDs are signed, opaque routing tokens. Store and pass them back unchanged; do not parse them or substitute a manager-local ID. Returned MCP and service-port URLs already use the scheduler's configured public_base_url, and sandbox proxy requests continue to use the sandbox's own token exposed by SandboxInfo/ServicePortInfo.

If you already have a sandbox MCP URL and token, connect directly to MCP:

import asyncio

from daimon_sdk import DaimonClient


async def main() -> None:
    async with DaimonClient("http://127.0.0.1:8080/mcp") as client:
        runtime = await client.runtime.get_context()
        print(runtime.base_workdir)

        result = await client.files.glob("**/*.rs", path=runtime.base_workdir)
        print(result.filenames[:5])

        bash = await client.exec.bash("printf 'hello from processd\\n'")
        print(bash.stdout)


asyncio.run(main())

Raw MCP vs SDK

Raw MCP:

payload = await mcp_client.call_tool("Read", {"file_path": "/tmp/demo.txt"})

SDK:

read = await client.files.read("/tmp/demo.txt")
print(read.file.content)

API Overview

• DaimonClient(base_url, access_token=None, timeout_s=30.0)
• await client.connect() / await client.close()
• async with DaimonClient(...) as client
• client.runtime.get_context()
• client.files.read() / write() / edit() / glob() / grep()
• client.exec.bash() / start_session()
• SessionHandle.write() / poll() / wait_for_exit() / close()
• client.web.fetch()
• client.raw.call_tool()
• DaimonManagerClient(base_url, access_token=None, timeout_s=30.0)
• await manager.health()
• await manager.capacity()
• await manager.create_sandbox()
• await manager.list_sandboxes(labels=..., states=...)
• await manager.find_sandbox(labels={"thread_id": thread_id})
• await manager.find_or_create_sandbox(labels={"thread_id": thread_id})
• await manager.get_sandbox(id)
• await manager.start_sandbox(id) / stop_sandbox(id) / delete_sandbox(id)
• await manager.update_sandbox(id, ttl_seconds=...)
• async with manager.sandbox() as sandbox
• await sandbox.set_ttl(ttl_seconds)
• sandbox.service_ports
• sandbox.get_service_port(port)
• sandbox.runtime/files/exec/web/raw

manager.sandbox() creates a sandbox, connects to its MCP endpoint, and deletes it on context exit by default. Use delete_on_exit=False or create_sandbox() when the workspace should survive beyond the context. find_sandbox(labels=...) is a read-only lookup by default and does not extend the sandbox TTL. Pass ttl_seconds=... only when you intentionally want the manager's compatibility renew behavior, or use find_or_create_sandbox(...) for normal acquire/renew flows. ttl_seconds=0 marks a sandbox as immediately expired so the next manager reaper loop deletes it.

Sandbox Service Ports

When a sandbox runs a service on a manager-configured port, the SDK exposes the connection information and leaves the request itself to your HTTP or WebSocket client:

import httpx

async with manager.sandbox() as sandbox:
    web = sandbox.get_service_port(3000)

    response = httpx.get(web.url + "hello.txt", headers=web.headers)
    print(response.text)

ServicePortInfo contains only port, url, token, and headers.

Local Testing

The SDK compatibility tests use the sibling core project in this monorepo:

processd/
  core/
  sdk/

Run tests with an environment that already has the dev dependencies installed:

PYTHONPATH=src python -m pytest -q

The E2E suite builds and launches ../core/target/debug/processd-mcp.

Manager E2E uses the sibling core Docker manager compose path:

PROCESSD_SDK_MANAGER_E2E=1 PYTHONPATH=src python -m pytest -q -m manager_e2e

Multi-replica scheduler E2E uses the sibling scheduler compose file. It starts two managers and two scheduler replicas, exercises the SDK across both schedulers, and verifies the 503 unavailable and 410 lost-node states:

PROCESSD_SDK_SCHEDULER_E2E=1 PYTHONPATH=src \
  python -m pytest -q -m scheduler_e2e

Release

Releases are published from GitHub Actions when a tag matching v* is pushed.

git tag v0.4.0
git push origin v0.4.0

The tag version must match pyproject.toml's project version.