Metadata-Version: 2.4
Name: kanyun-sandbox
Version: 0.3.0
Summary: Python SDK for Kanyun Sandbox v2 control plane
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# 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

```bash
cd sdk/python
pip install .
```

- package name: `kanyun-sandbox`
- import: `kanyun_sandbox`

## Quick Start

```python
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

```python
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:

```python
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.
