kanyun-sandbox 0.3.1

Python SDK for Kanyun Sandbox v2 control plane

Kanyun Sandbox Python SDK

Python SDK for the Kanyun Sandbox v2 control plane.

The SDK is image-agnostic by default. It can create, query, list, and delete sandboxes for any configured template. Agent access is optional and requires an explicit agent_client_factory for images that expose a compatible agent service.

Install

cd sdk/python
pip install .

• package name: kanyun-sandbox
• import: kanyun_sandbox

Quick Start

from kanyun_sandbox import Client

client = Client(
    control_plane_url="http://127.0.0.1:8080",
    api_key="kanyun_xxx",
)

with client.run_session(template_name="python-dev", ttl_seconds=300) as session:
    print(session.info.claim_name or session.info.sandbox_name)

Client

client = Client(
    control_plane_url="http://127.0.0.1:8080",
    api_key="kanyun_xxx",
    agent_port=8080,
    agent_client_factory=None,
)

Implemented methods:

• create_sandbox(request)
• get_sandbox(id)
• list_sandboxes()
• get_sandbox_detail(id)
• list_sandbox_events(id)
• delete_sandbox(id)
• extend_sandbox(id, ttl_seconds)
• connect_sandbox(id)
• new_session(request)
• run_session(...)
• list_templates()
• get_template(name)
• apply_template(name, request) / delete_template(name)
• list_template_materializations(name) / resync_template_materialization(name)
• list_warm_pools() / get_warm_pool(name) / apply_warm_pool(name, request) / delete_warm_pool(name)
• list_sandbox_history(...) / get_sandbox_history(id)
• Platform profile helpers for clusters, runtime profiles, build profiles, registry profiles, secret profiles, secret materializations, rotate, and resync
• Image build and asset helpers for builds, logs, cancellation, and reusable image assets

SandboxInfo.public_endpoints is populated when templates define ingress blueprints.

Optional Agent Adapter

If your template image runs a compatible agent service, install that client separately and pass a factory:

from agent_sandbox import Sandbox
from kanyun_sandbox import Client

client = Client(
    control_plane_url="http://127.0.0.1:8080",
    api_key="kanyun_xxx",
    agent_client_factory=lambda base_url: Sandbox(base_url=base_url),
)

with client.run_session(template_name="agent-enabled-devbox", ttl_seconds=300) as session:
    result = session.agent.shell.exec_command(command="pwd")
    print(result)

Agent clients are created lazily. Creating or connecting a sandbox does not require agent support. Accessing handle.agent or session.agent without a factory raises SandboxAgentUnavailableError; accessing agent before an IP is available raises SandboxNotReadyError.

Extend Sandbox TTL

from kanyun_sandbox import Client

client = Client(
    control_plane_url="http://127.0.0.1:8080",
    api_key="kanyun_xxx",
)

with client.run_session(template_name="python-dev", ttl_seconds=300) as session:
    # Extend the sandbox by another 600 seconds from now
    session.extend(600)

Only sandboxes in Running state can be extended. The new expiry cannot exceed the template's maxTTL (measured from creation time).

Authentication

All control-plane requests use X-API-Key.

Agent Connection Rule

When agent access is enabled:

1. Read SandboxInfo.ip.
2. Build http://{ip}:8080, or use the configured agent_port.
3. Do not fall back to endpoint.

Migration Notes

The v2 SDK keeps the familiar Client, SandboxHandle, Session, and run_session(...) flow. Unlike the old SDK, .agent is not assumed to exist for every sandbox. Use control-plane methods for generic images, and opt into .agent only for templates whose image implements the expected agent protocol.