── no router headers
or http:// if use_pod_ip ── no router headers
LocalTunnel rejected at __init__ (ValueError)
```
The `_inject_router_headers` flag is `False` only for `SandboxInClusterConnectionConfig`. In all other modes, every request carries `X-Sandbox-ID`, `X-Sandbox-Namespace`, `X-Sandbox-Port`, and (when available) `X-Sandbox-Pod-IP`, which lets the router route to the correct backend.
Sources: [clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_connector.py:38-91](), [clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_connector.py:125-149]()
### Pod-IP resolution and the auth latch
The connector caches a pod IP for routing speed, but it must defend against permission errors:
- First time around it calls the `get_pod_ip` callback (provided by `AsyncSandbox.get_pod_ip`).
- If the call raises and the underlying response is `401`/`403`, `_pod_ip_auth_failed` is **permanently** set on this client instance — pod-IP routing is disabled for its lifetime to avoid hammering the K8s API with a token that cannot read sandboxes.
- Transient errors are logged at debug and retried on later requests.
For `SandboxInClusterConnectionConfig`, `_resolve_base_url` upgrades the URL once pod-IP resolution succeeds, otherwise it falls back to cluster DNS.
Sources: [clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_connector.py:69-149]()
### Retry and cache invalidation
`send_request` retries up to `MAX_RETRIES = 5` times on `{500, 502, 503, 504}` with exponential backoff (`BACKOFF_FACTOR * 2**attempt`, i.e. 0.5 s, 1 s, 2 s, …). On any HTTP error it raises `SandboxRequestError` and clears caches that may have gone stale:
- For `SandboxGatewayConnectionConfig`, the `_base_url` is dropped so the next request re-queries the gateway IP.
- Pod-IP caching state (`_pod_ip_resolved`, `_cached_pod_ip_url`, `_pod_ip`) is reset.
`close()` calls `httpx.AsyncClient.aclose()` and clears the same caches.
```mermaid
sequenceDiagram
participant Caller as AsyncCommandExecutor/AsyncFilesystem
participant Conn as AsyncSandboxConnector
participant K8s as AsyncK8sHelper
participant Router as Sandbox router / pod
Caller->>Conn: send_request(METHOD, endpoint, ...)
Conn->>Conn: _resolve_base_url()
alt Gateway mode, no cached IP
Conn->>K8s: wait_for_gateway_ip(...)
K8s-->>Conn: ip_address
else InCluster + use_pod_ip
Conn->>K8s: get_pod_ip via callback
K8s-->>Conn: podIPs[0] or None
end
Conn->>Router: httpx.AsyncClient.request(...)
alt 5xx and attempt < 5
Router-->>Conn: retryable status
Conn->>Conn: asyncio.sleep(0.5 * 2^attempt)
Conn->>Router: retry
end
Router-->>Caller: httpx.Response (or SandboxRequestError)
```
Sources: [clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_connector.py:33-208]()
## `AsyncK8sHelper`
`AsyncK8sHelper` wraps `kubernetes_asyncio` and is shared by the client and all of its sandboxes through `AsyncSandbox.k8s_helper`. Initialization is lazy and once-only: an `asyncio.Lock` guards `_ensure_initialized`, which tries in-cluster config first and falls back to `load_kube_config()`. `close()` shuts down the shared `ApiClient` and resets the latch so a later call would re-initialize cleanly.
### CRD operations
| Method | Resource | Behavior |
| --- | --- | --- |
| `create_sandbox_claim(name, template, namespace, annotations, labels, lifecycle, warmpool)` | `SandboxClaim` | Builds a manifest with `spec.sandboxTemplateRef`, optional `spec.lifecycle` and `spec.warmpool`; calls `create_namespaced_custom_object`. |
| `resolve_sandbox_name(claim_name, namespace, timeout)` | `SandboxClaim` (watch) | Watches the claim until `status.sandbox.name` is populated (warm-pool adoption may produce a different name from the claim). Surfaces `Ready=False` + `TemplateNotFound` as `SandboxTemplateNotFoundError`. Supports both `name` (post-rename) and legacy `Name` keys. |
| `wait_for_sandbox_ready(name, namespace, timeout)` | `Sandbox` (watch) | Watches until a condition with `type=Ready, status=True`. Returns the first `status.podIPs` entry (or `None` on older controllers). |
| `delete_sandbox_claim(name, namespace)` | `SandboxClaim` | `404` swallowed; other API errors raise `SandboxNotFoundError`. |
| `get_sandbox`, `get_sandbox_claim` | both | Return the raw object dict or `None` on `404`. |
| `list_sandbox_claims(namespace, label_selector)` | `SandboxClaim` | Returns `metadata.name` for each item, optionally filtered by selector. |
| `wait_for_gateway_ip(gateway_name, namespace, timeout)` | `Gateway` (watch) | Watches the Gateway custom resource for `status.addresses[0].value`. |
All watch-based methods (`resolve_sandbox_name`, `wait_for_sandbox_ready`, `wait_for_gateway_ip`) follow the same pattern: compute a remaining-time budget, open a `watch.Watch()`, iterate `w.stream(...)` with `timeout_seconds=remaining`, and always `await w.close()` in a `finally` block to release the streaming HTTP connection — important because `kubernetes_asyncio` watches hold a live connection until closed.
Sources: [clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_k8s_helper.py:37-331]()
## `AsyncCommandExecutor`
The executor is a thin wrapper over `connector.send_request("POST", "execute", json={"command": ...}, timeout=...)`. The response is parsed into the shared `ExecutionResult` Pydantic model (`stdout`, `stderr`, `exit_code`); decode or schema failures are raised as `RuntimeError` so callers can distinguish them from `SandboxRequestError`. The whole `run` method is wrapped in `@async_trace_span("run")`, with `sandbox.command` and `sandbox.exit_code` recorded as span attributes when tracing is recording.
```python
# clients/python/agentic-sandbox-client/k8s_agent_sandbox/commands/async_command_executor.py:30-56
@async_trace_span("run")
async def run(self, command: str, timeout: int = 60) -> ExecutionResult:
...
response = await self.connector.send_request("POST", "execute", json={"command": command}, timeout=timeout)
...
return ExecutionResult(**response.json())
```
Sources: [clients/python/agentic-sandbox-client/k8s_agent_sandbox/commands/async_command_executor.py:20-57](), [clients/python/agentic-sandbox-client/k8s_agent_sandbox/models.py:18-22]()
## `AsyncFilesystem`
`AsyncFilesystem` mirrors the four core sync filesystem methods, all decorated with `@async_trace_span(...)`:
| Method | HTTP | Notes |
| --- | --- | --- |
| `write(path, content, timeout, allow_unsafe_paths)` | `POST /upload` | Encodes `str` content as UTF-8 bytes; routes through `Filesystem._safe_upload_path` unless `allow_unsafe_paths=True`. |
| `read(path, timeout, allow_unsafe_paths)` | `GET /download/{path}` | Same path sanitization gate. Returns `response.content` bytes. |
| `list(path, timeout)` | `GET /list/{path}` | Parses into `list[FileEntry]`. |
| `exists(path, timeout)` | `GET /exists/{path}` | Returns the `exists` boolean from the JSON body. |
The path-safety contract is shared with the sync class via direct call into `Filesystem._safe_upload_path` (re-implementing it asynchronously would risk drift). The accompanying comment explains why `os.path.basename` is not sufficient — `basename("foo\x00../etc/passwd")` returns the string unchanged because of the embedded NUL, which would then truncate at the C layer when handed to the OS. The hardened sanitizer rejects empty / bare-`.`, embedded NUL and ASCII control characters, and any `..` segment after normalisation. URL-path interpolation goes through `urllib.parse.quote(path, safe="")` on every read/list/exists call.
Sources: [clients/python/agentic-sandbox-client/k8s_agent_sandbox/files/async_filesystem.py:24-139]()
## Optional dependency boundary
The async stack is opt-in. The top-level `__init__.py` imports `AsyncSandboxClient` from `async_sandbox_client`; on `ImportError` it replaces the symbol with a stub class whose `__init__` raises a guided `ImportError` telling the caller to install the `async` extra. This keeps the sync surface usable on minimal installations while still letting users `from k8s_agent_sandbox import AsyncSandboxClient` and discover the missing-extras error at instantiation time rather than at import time.
```python
# clients/python/agentic-sandbox-client/k8s_agent_sandbox/__init__.py:26-35
try:
from .async_sandbox_client import AsyncSandboxClient
except ImportError:
class AsyncSandboxClient: # type: ignore[no-redef]
def __init__(self, *args, **kwargs):
raise ImportError(
"AsyncSandboxClient requires the 'async' extras. "
"Install with: pip install k8s-agent-sandbox[async]"
)
```
Sources: [clients/python/agentic-sandbox-client/k8s_agent_sandbox/__init__.py:26-35]()
## Sync vs. Async at a glance
The two stacks share models, label-validation rules, path sanitization, and tracing decorators. The differences worth knowing before choosing:
| Aspect | Sync | Async |
| --- | --- | --- |
| Local development via `kubectl port-forward` | Supported (`SandboxLocalTunnelConnectionConfig`) | **Not supported** — connector rejects it; client refuses `connection_config=None` |
| Process-exit safety net | `atexit` cleanup | None; must use `async with` or explicit `delete_all` + `close` |
| HTTP transport | `requests` | `httpx.AsyncClient` (transport-level retries=3) |
| K8s API | `kubernetes` | `kubernetes_asyncio` (watches must be closed in `finally`) |
| Mutual exclusion | `threading.Lock` | `asyncio.Lock` |
| Cancellation handling on create | Exceptions | `Exception | CancelledError`, claim cleanup under `asyncio.shield` |
Sources: [clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_sandbox_client.py:50-173](), [clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_connector.py:55-91](), [clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_k8s_helper.py:107-207]()
## Putting it together
A minimal end-to-end async session — provision a sandbox, run a command, upload and download a file, and let the context manager clean up — exercises every layer described above:
```python
from k8s_agent_sandbox import AsyncSandboxClient
from k8s_agent_sandbox.models import SandboxDirectConnectionConfig
async def main():
config = SandboxDirectConnectionConfig(api_url="http://router.example")
async with AsyncSandboxClient(connection_config=config) as client:
sandbox = await client.create_sandbox(
template="python-sandbox-template",
shutdown_after_seconds=600,
)
result = await sandbox.commands.run("echo hello")
await sandbox.files.write("/tmp/note.txt", "hi")
data = await sandbox.files.read("/tmp/note.txt")
# __aexit__ -> delete_all() -> client.close() releases all claims
```
The `async with` block is what makes this safe: it guarantees `delete_all()` runs even if the body raises, which is the only reliable cleanup path given the deliberate absence of an `atexit` fallback.
Sources: [clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_sandbox_client.py:41-105](), [clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_sandbox_client.py:107-173]()