kanyun-sandbox 0.3.0

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)
• 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.

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.