Capsule SDK

The Capsule SDK is the recommended client surface for registering workloads, triggering builds, allocating runners, and interacting with running Capsule sandboxes from Python.

Requirements

• Python >= 3.10
• access to a running Capsule control plane
• a GCP KMS attestation key for authenticated requests (auto-derived from tenant ID by default)

Installation

pip install capsule-sdk

For local development:

cd sdk/python
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Configuration

The SDK can be configured directly in code or through environment variables.

Example:

export CAPSULE_CONTROL_PLANE_ADDR="http://localhost:8080"
# KMS key name is auto-derived from tenant_id if not set:
# export CAPSULE_KMS_KEY_NAME="projects/{tenant}/locations/global/keyRings/capsule/cryptoKeys/capsule-attestation/cryptoKeyVersions/1"

Quickstart

The fastest way to get started is the high-level workloads API.

from capsule_sdk import CapsuleClient, RunnerConfig

cfg = (
    RunnerConfig("My dev sandbox")
    .with_base_image("ubuntu:22.04")
    .with_commands(["apt-get update", "apt-get install -y python3"])
    .with_tier("m")
    .with_ttl(3600)
    .with_auto_pause(True)
    .with_auto_rollout(True)
)

with CapsuleClient(control_plane_addr="http://localhost:8080", tenant_id="my-tenant") as client:
    workload = client.workloads.onboard(cfg)

    with client.workloads.start(workload) as runner:
        output, code = runner.exec_collect("python3", "-c", "print('hello')")
        print(output, code)

        runner.write_text("/workspace/hello.txt", "hello")
        print(runner.read_text("/workspace/hello.txt"))

Onboard From YAML

You can also onboard directly from an onboard.yaml-style file:

from capsule_sdk import CapsuleClient

with CapsuleClient(control_plane_addr="http://localhost:8080", tenant_id="my-tenant") as client:
    workload = client.workloads.onboard_yaml(
        "examples/afs/onboard.yaml",
        name="afs-sandbox",
    )

    with client.workloads.start("afs-sandbox") as runner:
        print(runner.read_text("/etc/hostname"))

The AFS example is an example workload name, not a special SDK mode. See examples/afs/ for the underlying config shape.

Async Quickstart

Use the async client in event-loop-native applications:

import asyncio

from capsule_sdk import AsyncCapsuleClient, RunnerConfig


async def main() -> None:
    cfg = (
        RunnerConfig("My async sandbox")
        .with_base_image("ubuntu:22.04")
        .with_commands(["echo async-ready"])
        .with_tier("m")
        .with_ttl(3600)
        .with_auto_pause(True)
    )

    async with AsyncCapsuleClient(control_plane_addr="http://localhost:8080", tenant_id="my-tenant") as client:
        workload = await client.workloads.onboard(cfg)
        runner = await client.workloads.start(workload)

        async with runner:
            result = await runner.exec_collect("sh", "-lc", "printf hello")
            print(result.stdout, result.exit_code)


asyncio.run(main())

Low-Level APIs

For finer control, work directly with the resource clients:

from capsule_sdk import CapsuleClient

with CapsuleClient(control_plane_addr="http://localhost:8080", tenant_id="my-tenant") as client:
    with client.runners.allocate_ready("my-workload-key") as runner:
        for event in runner.exec("echo", "hello"):
            if event.type == "stdout":
                print(event.data, end="")

Key low-level surfaces:

• client.runners
• client.workloads
• client.snapshots
• client.runner_configs

Multi-Tenant Builder Config

When running builds in a tenant's own GCP project, set the tenant GCE config on RunnerConfig. Builds will launch in the tenant's project while pulling the base builder image from central.

cfg = (
    RunnerConfig("my-sandbox")
    .with_base_image("ubuntu:22.04")
    .with_commands(["pip install -e ."])
    .with_tier("m")
    .with_tenant_gce_config(
        project="tenant-project-123",
        zone="us-central1-a",
        network="projects/tenant-project-123/global/networks/default",
        subnet="projects/tenant-project-123/regions/us-central1/subnetworks/default",
        service_account="builder@tenant-project-123.iam.gserviceaccount.com",
    )
)

Individual fields can also be set separately:

cfg = (
    RunnerConfig("my-sandbox")
    .with_tenant_gcp_project("tenant-project-123")
    .with_tenant_gcp_zone("us-central1-a")
)

Two tenants can register the same display name without conflict — the server qualifies the config ID with the tenant project automatically.

Credential Broker Proxy

To route runner traffic through the credential broker, register a sandbox with QE to obtain a sandbox_token, then pass it as proxy_token during allocation. The control plane resolves the per-tenant proxy address from the TF-managed capsule-credential-broker-addrs ConfigMap (mounted at /etc/capsule/broker_addrs.json, reloaded ~1 min).

with CapsuleClient() as client:
    runner = client.runners.allocate_ready(
        "my-workload-key",
        session_id="session-abc",
        proxy_token=sandbox_token,
    )

This configures the runner to:

• Route all egress through the tenant's broker proxy (deny-all except proxy IP)
• Fetch the proxy CA certificate from Secret Manager
• Use proxy_token as the basic-auth username in proxy requests

The same parameters are available on allocate(), allocate_ready(), from_config(), and workloads.start() / workloads.allocate().

Key Concepts

Runner and session IDs

• After allocation, prefer session_id for anything that hits the host HTTP API directly: Runners.file_download, file_upload, file_read, file_write, file_list, file_stat, file_remove, file_mkdir, exec, and shell take session_id as the first argument (or embed it in the URL). Those requests go to paths such as /api/v1/sessions/{session_id}/files/... or /api/v1/sessions/{session_id}/exec on the host address returned by the control plane. The legacy /api/v1/runners/{runner_id}/... paths remain available for callers that key off runner_id only.
• On the control plane, runners.status, runners.release, and runners.pause accept runner_id= or session_id= (exactly one). The SDK caches the host address by session_id when the allocate/status response includes one.

RunnerConfig Builder Methods

Retry And Timeout Behavior

• request_timeout applies to a single HTTP request
• startup_timeout covers "get me a usable runner"
• operation_timeout applies to host-side file, PTY, and stream operations
• allocate() retries transient control-plane and capacity errors until startup_timeout
• workloads.start() is the preferred high-level path for named workloads
• from_config() waits for runner readiness by default; use wait_ready=False for lower-level control

Host Reconnection

The SDK caches host addresses returned by allocate() and connect(), keyed by session_id when known (otherwise by runner_id). If a host proxy becomes unavailable during a safe retryable operation, the SDK will refresh the host via connect() and retry once when possible.

Live End-To-End Test

The repository includes an explicit live SDK E2E at sdk/python/tests/e2e_live.py. It exercises config registration, build enqueue, allocation, exec, file ops, PTY, pause/resume, release, and config cleanup against a real control plane.

Run it with:

make sdk-python-e2e

If you are not using the default address:

CAPSULE_BASE_URL="http://localhost:8080" make sdk-python-e2e

Development Checks

python -m ruff check src/capsule_sdk/ tests/
python -m ty check
python -m pytest tests/ -v --ignore=tests/e2e_live.py --ignore=tests/e2e_live_async.py

For contract tests against a live control plane:

CAPSULE_BASE_URL=http://localhost:8080 CAPSULE_TENANT_ID=test-tenant \
  python -m pytest tests/test_contract.py -v -m contract