Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs(sandbox): document released Fleet APIs and package boundaries (#3560)

Francesco Bonacci935807dac284
diff --git a/docs/content/docs/how-to-guides/sandbox/share-service-with-signed-url.mdx b/docs/content/docs/how-to-guides/sandbox/share-service-with-signed-url.mdx
index 7dd6bc1d48..6abe9bbec9 100644
--- a/docs/content/docs/how-to-guides/sandbox/share-service-with-signed-url.mdx
+++ b/docs/content/docs/how-to-guides/sandbox/share-service-with-signed-url.mdx
@@ -1,10 +1,9 @@
---
title: Share a sandbox service with a signed URL
-description: Create, list, and revoke time-limited public URLs for sandbox services with Python or TypeScript.
+description: Create, list, and revoke time-limited public URLs for sandbox services with the TypeScript Fleet SDK.
---
import { Callout } from 'fumadocs-ui/components/callout';
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
Use a signed service URL when a person or external system needs temporary
access to a service running inside a Fleet sandbox. The URL is public,
@@ -22,7 +21,13 @@ the bound sandbox.
- A Fleet pool whose template exposes the service you want to share.
- A bound sandbox claim. The signed URL does not create or keep a claim alive.
- OAuth client credentials with permission to manage the claim.
-- A Cua Sandbox or Fleet SDK release that includes signed service URL support.
+- The published `@trycua/fleet` 0.1.1 TypeScript package and a Node.js environment
+ with `fetch` and `AbortSignal.timeout`.
+
+The published Python `cua-sandbox` 0.4.3 package exposes
+`sandbox.services.request()`, but does not expose `create_signed_url()`,
+`list_signed_urls()`, or `revoke_signed_url()`. Use the TypeScript API below
+for signed URLs. See the [service reference](/reference/sandbox-sdk/interfaces#services).
If you do not have a pool yet, create one with
[Python](/how-to-guides/sandbox/create-pool-with-python) or
@@ -36,8 +41,10 @@ optional label is useful for recording why a link was created and is limited to
## Authenticate
-Both SDKs connect to `https://run.cua.ai` by default. Set OAuth client
-credentials before running either example:
+Obtain credentials through
+[Fleet authentication](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials).
+This example uses OAuth client credentials and the `https://run.cua.ai` Fleet
+endpoint. Set the credentials and resource names before running it:
```bash
export CUA_CLIENT_ID="<your-client-id>"
@@ -51,86 +58,14 @@ or OAuth endpoints.
## Create and revoke a signed URL
-The examples claim a sandbox from an existing pool, create a one-hour URL for
-the `mcp` service, wait while you use the URL, and then revoke it before
+The example claims a sandbox from an existing pool, creates a one-hour URL for
+the `mcp` service, waits while you use the URL, and then revokes it before
releasing the claim.
-<Tabs groupId="signed-service-url-language" persist items={['Python', 'TypeScript']}>
- <Tab value="Python">
-
-This example uses [`uv`](https://docs.astral.sh/uv/) and the same self-contained
-script setup as the Python pool guide. `uv` installs `cua-sandbox` in an
-isolated environment when you run the script.
-
-Save the following script as `share_service.py`:
-
-```python title="share_service.py"
-# /// script
-# requires-python = ">=3.11,<3.14"
-# dependencies = [
-# "cua-sandbox",
-# ]
-# ///
-
-import asyncio
-import os
-
-from cua_sandbox import Pool
-
-
-POOL_NAME = os.environ["CUA_POOL_NAME"]
-CLAIM_NAME = os.environ.get("CUA_CLAIM_NAME", "signed-url-demo")
-SERVICE_NAME = "mcp"
-
-
-async def main() -> None:
- pool = await Pool.get(POOL_NAME)
-
- async with pool.claim(
- name=CLAIM_NAME,
- service=SERVICE_NAME,
- time_to_start=900,
- ) as sandbox:
- signed_url = await sandbox.services.create_signed_url(
- SERVICE_NAME,
- label="Customer demo",
- expires_in_seconds=3600,
- )
-
- try:
- print(f"Share this URL: {signed_url.url}")
-
- urls = await sandbox.services.list_signed_urls()
- for item in urls:
- state = "revoked" if item.revoked_at else "available"
- print(f"{item.label or item.id}: {state}, expires {item.expires_at}")
-
- await asyncio.to_thread(input, "Press Enter to revoke the URL... ")
- finally:
- await sandbox.services.revoke_signed_url(signed_url)
-
-
-asyncio.run(main())
-```
-
-Run it:
-
-```bash
-uv run share_service.py
-```
-
-`pool.claim()` keeps the claim bound for the duration of the context manager.
-The `finally` block revokes the URL even when the work inside the block raises
-an exception. Exiting the context then releases the claim while leaving the
-pool warm.
-
- </Tab>
- <Tab value="TypeScript">
-
Install the Fleet SDK and a TypeScript runner:
```bash
-npm install @trycua/fleet@^0.1.1
+npm install @trycua/[email protected]
npm install --save-dev tsx typescript
npm pkg set type=module
```
@@ -231,9 +166,6 @@ The Fleet client manages signed URLs directly. Keep the returned
the URL and namespace. The nested cleanup blocks revoke the URL, release the
claim, and destroy the native client in that order.
- </Tab>
-</Tabs>
-
## Use the URL safely
- Keep the claim bound while clients use the URL. Releasing or deleting the
@@ -262,6 +194,7 @@ lifecycle.
### The SDK says signed service URLs are unavailable
-Confirm that your installed Cua Sandbox or Fleet SDK includes signed service
-URL support and that the Fleet environment has the feature configured. Older
-SDK bindings do not expose the create, list, or revoke operations.
+Confirm that the Fleet environment has signed service URLs configured. The
+TypeScript `@trycua/fleet` 0.1.1 package includes the create, list, and revoke
+operations, but package availability does not enable the feature on the server.
+The Python `cua-sandbox` 0.4.3 service interface does not include these methods.
diff --git a/docs/content/docs/reference/sandbox-sdk/image.mdx b/docs/content/docs/reference/sandbox-sdk/image.mdx
index d37589f22c..cf14dce331 100644
--- a/docs/content/docs/reference/sandbox-sdk/image.mdx
+++ b/docs/content/docs/reference/sandbox-sdk/image.mdx
@@ -3,12 +3,34 @@ title: Image reference
description: "API reference for the Image class: the immutable, chainable image specification used to configure sandbox environments."
---
-`Image` is an *immutable, chainable image specification*. Each method returns a new `Image` instance; the original is unchanged. Import from `cua`:
+`Image` is an immutable, chainable image specification in `cua-sandbox` 0.4.3.
+Each builder method returns a new `Image` instance; the original is unchanged.
+Import it from `cua_sandbox`:
```python
-from cua import Image
+from cua_sandbox import Image
```
+## Fleet image constraints
+
+`Pool.apply()` accepts an explicit registry reference or a built-in descriptor
+that resolves to a registry image. Fleet rejects images with setup layers,
+environment variables, copied files, snapshot sources, or local disk paths.
+Exposed service ports are accepted. An OCI reference for Fleet must identify a
+compatible container disk; an arbitrary application container is not a VM disk.
+
+In 0.4.3, the built-in registry mappings are `Image.linux()` with Ubuntu 24.04
+and `kind='vm'`, and `Image.windows()` with version `'2022'` and `kind='vm'`.
+Other descriptors require an explicit compatible registry image for Fleet.
+These mappings describe client image selection, not deployment certification.
+
+The builder methods below describe image specifications. They do not establish
+that every runtime, operating system, or cloud deployment executes those
+specifications. Local runtime selection and legacy cloud provisioning are
+separate from Fleet. See [Pool reference](/reference/sandbox-sdk/pool) for Fleet
+configuration and [Sandbox creation](/reference/sandbox-sdk#sandbox-creation)
+for backend selection.
+
## Constructors
### Image.linux
@@ -18,7 +40,8 @@ from cua import Image
def linux(cls, distro: str = 'ubuntu', version: str = '24.04', kind: str = 'vm') -> Image
```
-Linux image. Defaults to `kind='vm'` (QEMU). `kind='container'` uses Docker/XFCE.
+Linux image specification. Defaults to `kind='vm'`; `kind='container'` describes
+a container. Local runtime selection depends on the host and installed runtime.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
@@ -33,26 +56,27 @@ Linux image. Defaults to `kind='vm'` (QEMU). `kind='container'` uses Docker/XFCE
def macos(cls, version: str = '26', kind: str = 'vm') -> Image
```
-macOS image. Always a VM (Apple Virtualization / Lume). Supported versions: `'15'` / `'sequoia'`, `'26'` / `'tahoe'`.
+macOS image specification. Version aliases include `'15'` / `'sequoia'` and
+`'26'` / `'tahoe'`. The constructor does not establish Fleet availability.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `version` | `str` | `'26'` | macOS version string or name |
-| `kind` | `str` | `'vm'` | Always `'vm'` |
+| `kind` | `str` | `'vm'` | VM specification; constructor does not validate runtime availability |
### Image.windows
```python
@classmethod
-def windows(cls, version: str = '11', kind: str = 'vm') -> Image
+def windows(cls, version: str = '2022', kind: str = 'vm') -> Image
```
-Windows image. Always a VM (QEMU or Hyper-V).
+Windows image specification. The released default is Windows Server `2022`.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
-| `version` | `str` | `'11'` | Windows version |
-| `kind` | `str` | `'vm'` | Always `'vm'` |
+| `version` | `str` | `'2022'` | Windows version |
+| `kind` | `str` | `'vm'` | VM specification; constructor does not validate runtime availability |
### Image.android
@@ -61,34 +85,40 @@ Windows image. Always a VM (QEMU or Hyper-V).
def android(cls, version: str = '14', kind: str = 'vm') -> Image
```
-Android image. Always a VM (QEMU emulator).
+Android image specification. This constructor does not establish Fleet support.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `version` | `str` | `'14'` | Android version |
-| `kind` | `str` | `'vm'` | Always `'vm'` |
+| `kind` | `str` | `'vm'` | VM specification; constructor does not validate runtime availability |
### Image.from_registry
```python
@classmethod
-def from_registry(cls, ref: str) -> Image
+def from_registry(cls, ref: str, *, os_type: str = 'linux', kind: Optional[str] = None) -> Image
```
-Image from an OCI registry reference. `kind` is resolved after pull.
+Image from an OCI registry reference. `os_type` identifies the guest operating
+system; it is not inferred from a tag. When omitted, `kind` remains unresolved
+until image resolution.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
-| `ref` | `str` | required | Registry reference, e.g. `'ghcr.io/trycua/macos-tahoe-cua:latest'` or `'ubuntu:22.04'` |
+| `ref` | `str` | required | OCI reference for an image appropriate to the selected backend |
+| `os_type` | `str` | `'linux'` | Guest OS; use `'windows'` for a Windows disk |
+| `kind` | `str or None` | `None` | Explicit `'vm'` or `'container'` kind |
### Image.from_file
```python
@classmethod
-def from_file(cls, path: str, os_type: str = 'windows', kind: str = 'vm', agent_type: Optional[str] = None) -> Image
+def from_file(cls, path: str, *, os_type: str = 'windows', kind: str = 'vm', agent_type: Optional[str] = None) -> Image
```
-Image from a local disk file, ISO, or URL. Supported formats: `qcow2`, `vhdx`, `raw`, `img`, `iso`. HTTP/HTTPS URLs are downloaded and cached automatically. Zip files are extracted. For ISOs, the runtime creates a `qcow2` disk and attaches the ISO as a CD-ROM. Downloaded images are cached in `~/.cua/cua-sandbox/image-cache/`.
+Local-runtime image from a disk file, ISO, or URL. Disk handling depends on the
+runtime. HTTP/HTTPS images are downloaded and cached under
+`~/.cua/cua-sandbox/image-cache/`. Fleet rejects `from_file()` specifications.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
@@ -110,7 +140,9 @@ Reconstruct an `Image` from a serialized spec dict (e.g. the output of `to_dict(
## Builder methods
-Each method returns a new `Image`. Builder calls are composable and can be chained in any order.
+Each method returns a new `Image`. These methods add setup instructions for a
+runtime that implements them. Fleet rejects setup layers; use an image with the
+required software already installed.
### Image.apt_install
@@ -195,7 +227,7 @@ Install Python packages via `pip`.
def uv_install(self, *packages: str) -> Image
```
-Install Python packages via `uv add` into the cua-server project. Faster than `pip_install`.
+Adds a `uv add` package-installation layer for the cua-server project.
### Image.run
@@ -227,7 +259,18 @@ Copy a local file into the image at the specified destination path.
def expose(self, port: int) -> Image
```
-Mark a port the sandbox will serve on. Used with `sb.tunnel.forward()`.
+Marks a port the sandbox will serve on. Fleet's default service mapping names
+it `port-N`, where `N` is the port, except for the server port. Local forwarding
+is reported by `sb.exposed_ports` where the runtime provides it.
+
+### Image.app_install
+
+```python
+def app_install(self, app_id: str) -> Image
+```
+
+Adds an application-installation layer by app catalog ID. Requires the runtime
+and application installer to support the selected app; Fleet rejects this layer.
---
diff --git a/docs/content/docs/reference/sandbox-sdk/index.mdx b/docs/content/docs/reference/sandbox-sdk/index.mdx
index 713958d3da..3796bf7c1b 100644
--- a/docs/content/docs/reference/sandbox-sdk/index.mdx
+++ b/docs/content/docs/reference/sandbox-sdk/index.mdx
@@ -1,173 +1,224 @@
---
title: Sandbox SDK reference
-description: "API reference for the Cua Sandbox Python package: Sandbox, Image, Localhost, and top-level functions."
+description: Packages, configuration, and Sandbox lifecycle APIs for Python and TypeScript.
---
-## Package
+## Packages
-`cua-sandbox` is a Python package imported as `cua`.
+This reference describes the published `cua-sandbox` 0.4.3 Python package and
+`@trycua/fleet` 0.1.1 TypeScript package.
-| Field | Value |
-|-------|-------|
-| Package | `cua-sandbox` |
-| Import name | `cua` |
-| Python version | 3.12+ |
-| Install | `pip install cua` |
+| Distribution | Import | Requirement | API |
+| --- | --- | --- | --- |
+| [`cua-sandbox` 0.4.3](https://pypi.org/project/cua-sandbox/0.4.3/) | `cua_sandbox` | Python `>=3.11,<3.14` | `Sandbox`, `Image`, `Pool`, `Template`, and interfaces |
+| [`cua` 0.1.6](https://pypi.org/project/cua/0.1.6/) | `cua` | Python `>=3.12,<3.14` | Umbrella package; reexports `Sandbox` and `Image`, but not `Pool` |
+| [`@trycua/fleet` 0.1.1](/reference/sandbox-sdk/typescript) | `@trycua/fleet/node` or `@trycua/fleet/browser` | Environment-specific WebAssembly entry point | Fleet client, resource types, and builders |
-## Top-level exports
+The Python Sandbox distribution can be installed independently:
-| Export | Description |
-|--------|-------------|
-| `Sandbox` | VM or container control class |
-| `Image` | Image builder class |
-| `Localhost` | Direct host control class |
-| `SandboxInfo` | Sandbox metadata structure |
-| `configure()` | Global SDK configuration function |
-| `login()` | Browser login function |
-| `whoami()` | Authenticated user lookup function |
-
-## Environment variables
+```bash
+pip install cua-sandbox==0.4.3
+```
-| Variable | Description |
-|----------|-------------|
-| `CUA_API_KEY` | Cua API key for cloud sandboxes |
+Its primary imports are:
-## Sandbox class
+```python
+from cua_sandbox import Image, Pool, Sandbox, Template
+```
-`Sandbox` controls a VM or container through `.mouse`, `.keyboard`, `.screen`, `.clipboard`, `.shell`, `.window`, `.terminal`, `.mobile`, and `.tunnel`.
+See [Pool and claim reference](/reference/sandbox-sdk/pool),
+[Image reference](/reference/sandbox-sdk/image),
+[Sandbox interfaces](/reference/sandbox-sdk/interfaces), and
+[TypeScript Fleet reference](/reference/sandbox-sdk/typescript).
-### Sandbox.ephemeral
+## Configuration and authentication
-Async context manager. The sandbox is destroyed automatically on exit.
+`configure()` updates process-wide settings. All parameters are optional,
+keyword-only strings; `None` leaves a setting unchanged.
```python
-async def ephemeral(cls, image: Image, name=None, api_key=None, local=False, runtime=None, cpu=None, memory_mb=None, disk_gb=None, region='us-east-1') -> AsyncIterator[Sandbox]
+def configure(
+ *, api_key=None, base_url=None, fleet_base_url=None, token_url=None,
+ client_id=None, client_secret=None, fleet_token=None,
+) -> None: ...
```
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `image` | `Image` | required | Image to run |
-| `name` | `str or None` | `None` | Optional name |
-| `api_key` | `str or None` | `None` | Cua API key; reads `CUA_API_KEY` if `None` |
-| `local` | `bool` | `False` | Use local runtime (Docker/Lume/QEMU) |
-| `runtime` | `Runtime or None` | `None` | Explicit runtime backend |
-| `cpu` | `int or None` | `None` | CPU count (cloud) |
-| `memory_mb` | `int or None` | `None` | Memory in MB (cloud) |
-| `disk_gb` | `int or None` | `None` | Disk size in GB (cloud) |
-| `region` | `str` | `'us-east-1'` | Cloud region |
+Fleet authentication uses a configured `fleet_token`, then `FLEETS_TOKEN`. If
+neither supplies a nonempty token, it uses `client_id` and `client_secret` from
+`configure()`, falling back to `CUA_CLIENT_ID` and `CUA_CLIENT_SECRET`.
-### Sandbox.create
+| Environment variable | Purpose | Default |
+| --- | --- | --- |
+| `FLEETS_TOKEN` | Fleet bearer token; takes precedence over OAuth client credentials | None |
+| `CUA_CLIENT_ID`, `CUA_CLIENT_SECRET` | Fleet OAuth client credentials | None |
+| `CUA_TOKEN_URL` | OAuth token endpoint | `https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token` |
+| `CUA_FLEET_BASE_URL` | Fleet API endpoint | `https://run.cua.ai` |
+| `CUA_API_KEY` | Legacy VM API key | None |
+| `CUA_BASE_URL` | Legacy VM API endpoint | `https://api.cua.ai` |
-Provisions a persistent sandbox. The sandbox keeps running after the script exits.
+Endpoint environment variables override the corresponding `configure()` values.
+Legacy API keys resolve from the per-call `api_key`, global configuration,
+`~/.cua/credentials`, then `CUA_API_KEY`.
-```python
-async def create(cls, image: Image, name=None, api_key=None, local=False, runtime=None, cpu=None, memory_mb=None, disk_gb=None, region='us-east-1') -> Sandbox
-```
+Credential acquisition is documented in
+[Fleet pools need their own credentials](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials).
+`login(base_url=None)` and `whoami(api_key=None)` belong to the legacy API-key
+flow; they do not configure Fleet OAuth credentials.
-Same parameters as `ephemeral`.
+## Sandbox creation
-### Sandbox.connect
+`Sandbox.create()` returns a connected `Sandbox`. `Sandbox.ephemeral()` is an
+async context manager that performs cleanup on exit.
-Connects to an existing sandbox by name. Supports both `await` and `async with`. When used as a context manager, `disconnect()` is called on exit. The sandbox keeps running.
+The complete `create()` signature is:
```python
-def connect(cls, name: str, api_key=None, local=False, ws_url=None, http_url=None, container_name=None, cpu=None, memory_mb=None, disk_gb=None, region='us-east-1') -> _ConnectResult
+async def create(
+ image=None, *, pool=None, name=None, replicas=1, service="server",
+ claim_spec=None, keep_alive_minutes=None, api_key=None, local=False,
+ runtime=None, cpu=None, memory_mb=None, disk_gb=None,
+ region="us-east-1", time_to_start=None, request_timeout=None,
+ server_port=8000, telemetry_enabled=True,
+) -> Sandbox: ...
```
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `name` | `str` | required | Sandbox name |
-| `api_key` | `str or None` | `None` | Cua API key; reads `CUA_API_KEY` if `None` |
-| `local` | `bool` | `False` | Use local runtime (Docker/Lume/QEMU) |
-| `ws_url` | `str or None` | `None` | WebSocket URL |
-| `http_url` | `str or None` | `None` | HTTP URL |
-| `container_name` | `str or None` | `None` | Container name |
-| `cpu` | `int or None` | `None` | CPU count (cloud) |
-| `memory_mb` | `int or None` | `None` | Memory in MB (cloud) |
-| `disk_gb` | `int or None` | `None` | Disk size in GB (cloud) |
-| `region` | `str` | `'us-east-1'` | Cloud region |
-
-### Sandbox instance methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `disconnect` | `async disconnect() -> None` | Drop transport connection. Sandbox keeps running. |
-| `destroy` | `async destroy() -> None` | Disconnect and permanently delete the sandbox. |
-| `screenshot` | `async screenshot(text=None, format='png', quality=95) -> bytes` | Capture screenshot. `format`: `'png'` or `'jpeg'`. `quality`: 1-95 (JPEG only). |
-| `screenshot_base64` | `async screenshot_base64(text=None, format='png', quality=95) -> str` | Screenshot as base64 string. |
-| `get_environment` | `async get_environment() -> str` | Returns `'linux'`, `'mac'`, `'windows'`, or `'browser'`. |
-| `get_display_url` | `async get_display_url(share=False) -> str` | URL to view the sandbox display. `share=True` returns a public link (cloud only). |
-| `get_dimensions` | `async get_dimensions() -> tuple[int, int]` | Screen width and height in pixels. |
-
-### Sandbox class methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `list` | `async list(local=False, api_key=None) -> list[SandboxInfo]` | List running and suspended sandboxes. |
-| `get_info` | `async get_info(name, local=False, api_key=None) -> SandboxInfo` | Metadata for a specific sandbox. |
-| `suspend` | `async suspend(name, local=False, api_key=None) -> None` | Suspend a sandbox (save state). Local QEMU: QMP snapshot. Local Docker: pause. Local Lume: stop. Cloud: `POST /v1/vms/{name}/stop`. |
-| `resume` | `async resume(name, local=False, api_key=None) -> Sandbox` | Resume a suspended sandbox. Returns connected `Sandbox`. |
-| `restart` | `async restart(name, local=False, api_key=None) -> Sandbox` | Restart (suspend then resume). Returns connected `Sandbox`. |
-| `delete` | `async delete(name, local=False, api_key=None) -> None` | Permanently delete. Local: stops and removes state file. Cloud: `DELETE /v1/vms/{name}`. |
-
-### Sandbox attributes
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `name` | `str or None` | Sandbox name |
-| `shell` | `Shell` | Run shell commands |
-| `mouse` | `Mouse` | Mouse control |
-| `keyboard` | `Keyboard` | Keyboard control |
-| `screen` | `Screen` | Screenshots and screen info |
-| `clipboard` | `Clipboard` | Clipboard read/write |
-| `tunnel` | `Tunnel` | Port forwarding |
-| `terminal` | `Terminal` | PTY sessions |
-| `window` | `Window` | Window management |
-| `mobile` | `Mobile` | Mobile (Android) touch and hardware keys |
-
-## SandboxInfo
-
-Returned by `Sandbox.list()` and `Sandbox.get_info()`.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `str` | Sandbox name |
-| `status` | `str` | Current status |
-| `source` | `str` | Runtime source |
-| `os_type` | `str or None` | OS type |
-| `host` | `str or None` | Host address |
-| `vnc_url` | `str or None` | VNC URL |
-| `api_url` | `str or None` | API URL |
-| `created_at` | `str or None` | ISO timestamp |
-
-## configure, login, whoami
+`ephemeral()` accepts the same parameters plus `keep_pool=False`.
+
+| Parameter | Type | Contract |
+| --- | --- | --- |
+| `image` | `Image or None` | Required when `pool` is omitted; mutually exclusive with `pool` |
+| `pool` | `Pool, str, or None` | Existing Fleet pool or pool name |
+| `name` | `str or None` | Claim name with `pool`; pool name for Fleet image-based `ephemeral`; sandbox name for local/legacy creation |
+| `replicas` | `int` | Pool replicas for Fleet image-based `ephemeral`; default `1` |
+| `service` | `str` | Fleet service to connect to; default `"server"` |
+| `claim_spec` | `ClaimSpec or None` | Explicit Fleet claim specification |
+| `keep_alive_minutes` | `float or None` | Renews an acquired Fleet claim's shutdown deadline; positive minutes |
+| `local` | `bool` | Selects local provisioning; default `False` |
+| `runtime` | Runtime instance or `None` | Explicit local runtime adapter |
+| `cpu`, `memory_mb`, `disk_gb` | `int or None` | Resource overrides where the selected backend accepts them |
+| `time_to_start` | `float or None` | Service startup timeout in seconds |
+| `request_timeout` | `float or None` | Transport request timeout where supported |
+| `server_port` | `int` | Server port, `1`–`65535`; default `8000` |
+| `api_key`, `region` | `str or None`, `str` | Legacy cloud options; region defaults to `"us-east-1"` |
+| `telemetry_enabled` | `bool` | Creation telemetry option; default `True` |
+| `keep_pool` | `bool` | `ephemeral()` only: retain the image-created Fleet pool after releasing the claim; requires `name` |
+
+### Fleet selection and constraints
+
+`pool=` explicitly selects Fleet. It rejects an image, resource overrides,
+`replicas != 1`, `local=True`, an explicit runtime or API key, a nondefault
+region, `request_timeout`, or a nondefault `server_port`. Configure the pool
+through `Pool.apply()` or `Pool.reconcile()` instead.
+
+For image-based calls, Fleet is selected when Fleet authentication is configured,
+no per-call `api_key` is supplied, the image resolves to a Fleet registry image,
+and neither `local=True` nor a runtime is supplied. Persistent Fleet creation
+requires an explicitly named pool: `Sandbox.create(image)` rejects this path.
+`Sandbox.ephemeral(image)` can create a disposable pool and claim. Fleet
+image-based provisioning rejects `disk_gb`, a nondefault region, and
+`request_timeout`.
+
+The presence of an image constructor does not establish backend support. See
+the [Fleet image constraints](/reference/sandbox-sdk/image#fleet-image-constraints).
+
+## Lifecycle and ownership
+
+Fleet pool configuration and claim lifetime are separate resources.
+
+| Operation | Fleet effect |
+| --- | --- |
+| `await pool.claim()` or `await Sandbox.create(pool=pool)` | Acquires a claim; caller owns its release |
+| `async with pool.claim()` | Acquires a claim and calls `close()` on exit |
+| `async with Sandbox.ephemeral(pool=pool)` | Releases the claim on exit; retains the supplied pool |
+| `async with Sandbox.ephemeral(image)` | Releases the claim and deletes its created pool/template on exit, unless `keep_pool=True` |
+| `await sb.disconnect()` | Closes the connection; does not release the claim |
+| `await sb.close()` | Releases a Fleet claim and disconnects; repeated calls are safe |
+| `await pool.delete()` | Deletes the pool; also deletes the template owned by that `Pool.apply()` result |
+
+`destroy()` is the local/legacy transport cleanup method. It does not release a
+claim obtained through `Pool.claim()`; use `close()` for that claim.
+Local and legacy `ephemeral()` call `destroy()` on exit, or suspend when the
+instance has snapshots. Cleanup can fail; it is not a guarantee of deletion.
+
+### Reconnection and renewal
+
+These methods apply to Fleet claim-backed instances:
+
+| Member | Signature or type | Contract |
+| --- | --- | --- |
+| `claim_name` | `str or None` | Claim identity, distinct from the bound sandbox's `name` |
+| `pool_name` | `str or None` | Pool owning the claim |
+| `to_dict` | `to_dict() -> dict[str, Any]` | Serializes claim identity and service, not credentials or a snapshot |
+| `from_dict` | `Sandbox.from_dict(data)` | Awaitable/context manager that reconnects; context exit disconnects without release |
+| `keep_alive` | `async keep_alive(*, minutes: float) -> None` | Moves the shutdown deadline to now plus positive minutes; caller must renew before expiry |
+| `close` | `async close() -> None` | Releases the claim and disconnects |
+
+The serialized shape is:
```python
-def configure(api_key=None, base_url=None) -> None
-# Set global SDK config. Equivalent to setting CUA_API_KEY.
-
-def login(base_url=None) -> None
-# Open Cua login page in browser; store credentials in ~/.cua/credentials (Clerk flow).
-
-def whoami(api_key=None) -> Dict[str, Any]
-# Return dict with user info (id, email, etc.) from Cua API.
+{
+ "version": 1,
+ "provider": "fleet",
+ "namespace": "example-pool",
+ "pool": "example-pool",
+ "claim": "example-claim",
+ "service": "server",
+}
```
-## Localhost
+`Sandbox.from_dict()` requires the namespace to match the pool. It still requires
+Fleet credentials and a claim that exists. Serialization, renewal, and `close()`
+raise `NotImplementedError` on instances without a Fleet claim handle.
-Direct host control via `cua_auto`. No sandbox. Attributes: `screen`, `mouse`, `keyboard`, `clipboard`, `shell`, `window`, `terminal`.
+## Other Sandbox methods
+
+`Sandbox.connect()` supports `await` and `async with`; context exit disconnects.
+For durable Fleet claim reconnection, use the serialized reference above.
```python
-# plain await
-host = await Localhost.connect()
-await host.shell.run('echo hello')
-await host.disconnect()
-
-# context manager
-async with Localhost.connect() as host:
- await host.shell.run('echo hello')
+def connect(
+ name: str, *, api_key=None, local=False, ws_url=None, http_url=None,
+ container_name=None, cpu=None, memory_mb=None, disk_gb=None,
+ region="us-east-1", telemetry_enabled=True,
+): ...
```
-Methods: same signatures as `Sandbox` (`screenshot`, `screenshot_base64`, `get_environment`, `get_dimensions`, `disconnect`).
-
-See [Sandbox interfaces reference](/reference/sandbox-sdk/interfaces) for the full API of sb.shell, sb.mouse, sb.keyboard, sb.screen, sb.clipboard, sb.tunnel, sb.terminal, sb.window, and sb.mobile. See [Image reference](/reference/sandbox-sdk/image) for the full Image builder API.
+The lifecycle class methods accept keyword-only `local=False, api_key=None`:
+
+| Method | Return type | Purpose |
+| --- | --- | --- |
+| `await Sandbox.list(...)` | `list[SandboxInfo]` | Lists local sandboxes, legacy VMs, or Fleet pools according to backend selection |
+| `await Sandbox.get_info(name, ...)` | `SandboxInfo` | Gets metadata |
+| `await Sandbox.suspend(name, ...)` | `None` | Requests backend-specific suspension |
+| `await Sandbox.resume(name, ...)` | `Sandbox` | Requests resume and connects |
+| `await Sandbox.restart(name, ...)` | `Sandbox` | Requests restart and connects |
+| `await Sandbox.delete(name, ...)` | `None` | Requests backend-specific deletion |
+
+These name-based operations are backend-specific. For an explicitly acquired
+Fleet claim, use `close()` to release it and `Pool.delete()` to remove its pool.
+
+The connected instance also provides these methods:
+
+| Method | Return type | Purpose |
+| --- | --- | --- |
+| `await sb.screenshot(text=None, format="png", quality=95)` | `bytes` | Captures PNG or JPEG bytes; `text` is unused in this release |
+| `await sb.screenshot_base64(text=None, format="png", quality=95)` | `str` | Captures a base64 screenshot |
+| `await sb.get_environment()` | `str` | Reports the transport's environment |
+| `await sb.get_dimensions()` | `tuple[int, int]` | Returns width and height in pixels |
+| `await sb.get_display_url(share=False)` | `str` | Returns a display URL where the transport supports it; shared links may embed credentials |
+| `await sb.snapshot(name=None, stateful=False)` | `Image` | Backend-specific snapshot operation; not implemented for Fleet claim-backed instances |
+
+`SandboxInfo` has required string fields `name`, `status`, and `source`, plus
+optional string fields `os_type`, `host`, `vnc_url`, `api_url`, and `created_at`.
+
+## Interfaces and Localhost
+
+`Sandbox` exposes `shell`, `files`, `mouse`, `keyboard`, `screen`, `clipboard`,
+`tunnel`, `terminal`, `window`, `mobile`, `services`, and `apps`. Availability
+depends on the connected transport. `exposed_ports` maps local guest ports to
+host ports; Fleet publishes named services instead.
+
+`Localhost.connect()` supports `await` and `async with` and controls the host
+through `cua_auto`, without a sandbox. Context exit disconnects. Its interfaces
+include `screen`, `mouse`, `keyboard`, `clipboard`, `shell`, `window`, and
+`terminal`. See [Sandbox interfaces](/reference/sandbox-sdk/interfaces).
diff --git a/docs/content/docs/reference/sandbox-sdk/interfaces.mdx b/docs/content/docs/reference/sandbox-sdk/interfaces.mdx
index 593ab2853f..c8f1cd12aa 100644
--- a/docs/content/docs/reference/sandbox-sdk/interfaces.mdx
+++ b/docs/content/docs/reference/sandbox-sdk/interfaces.mdx
@@ -1,11 +1,17 @@
---
title: Sandbox interfaces reference
-description: API reference for sb.shell, sb.mouse, sb.keyboard, sb.screen, sb.clipboard, sb.tunnel, sb.terminal, sb.window, and sb.mobile.
+description: Python Sandbox computer-control, file, service, tunnel, and application interfaces in cua-sandbox 0.4.3.
---
+These interfaces are exposed by `Sandbox` in the published `cua-sandbox` 0.4.3
+package. A method's presence does not guarantee support by every transport.
+Fleet claims route computer-server operations through the selected named
+service; local and legacy transports have different capabilities.
+
| Attribute | Class | Purpose |
|-----------|-------|---------|
| sb.shell | Shell | Run shell commands |
+| sb.files | Files | Read, write, and transfer files |
| sb.mouse | Mouse | Mouse control |
| sb.keyboard | Keyboard | Keyboard control |
| sb.screen | Screen | Screenshots and screen info |
@@ -14,11 +20,13 @@ description: API reference for sb.shell, sb.mouse, sb.keyboard, sb.screen, sb.cl
| sb.terminal | Terminal | PTY terminal sessions |
| sb.window | Window | Window management |
| sb.mobile | Mobile | Mobile (Android) touch and hardware-key control |
+| sb.services | Services | Send requests to named services |
+| sb.apps | Apps | Install and launch catalog applications |
## Shell
```python
-async def run(command: str, timeout: int = 30) -> CommandResult
+async def run(command: str, timeout: int = 30, background: bool = False) -> CommandResult
```
### CommandResult
@@ -60,7 +68,7 @@ async def key_up(key: str) -> None
```python
async def screenshot(format: str = 'png', quality: int = 95) -> bytes
-# format: 'png' (lossless) or 'jpeg' (lossy, ~5-10x smaller). quality: 1-95, ignored for PNG.
+# format: 'png' (lossless) or 'jpeg' (lossy). quality: 1-95, ignored for PNG.
async def screenshot_base64(format: str = 'png', quality: int = 95) -> str
# Screenshot as base64-encoded string.
@@ -85,11 +93,19 @@ async def set(text: str) -> None
def forward(*ports) -> _TunnelContext
```
-Forwards one or more sandbox ports (or Android abstract sockets) to the host.
+Requests forwarding for one or more sandbox ports or Android abstract sockets
+from the connected transport. Supports `await` and `async with`; context exit
+closes the forwards.
+
+In 0.4.3, the `FleetTransport` used by `Pool.claim()` does not implement
+`tunnel.forward()`. Use `sb.services.request()` for authenticated HTTP requests
+to a Fleet service. Local HTTP transports also do not implement this tunnel
+API; use `sb.exposed_ports` for ports forwarded at local startup.
*ports* may be int (TCP port) or str (Android abstract socket name, e.g. 'chrome_devtools_remote').
Returns:
+
- single TunnelInfo when one target is given
- dict[sandbox_port, TunnelInfo] when multiple targets are given
@@ -97,16 +113,67 @@ Returns:
| Field | Type | Description |
|-------|------|-------------|
-| host | str | Always 'localhost' |
-| port | int | Host-side port assigned |
+| host | str | Host chosen by the transport |
+| port | int | Port chosen by the transport |
| sandbox_port | int or str | Original port/socket inside the sandbox |
-| url | str (property) | `http://{host}:{port}` |
+| url | str (property) | Explicit transport URL, or `http://{host}:{port}` when none is supplied |
```python
async def close() -> None
# Close this tunnel. No-op if already closed or inside a context manager.
```
+## Services
+
+Sends an authenticated request to a named service on the connected sandbox:
+
+```python
+async def request(
+ name: str, *, method: str, path: str, json: Any = None,
+ headers: dict[str, str] | None = None,
+) -> Any: ...
+```
+
+For Fleet claims, `name` must be in the bound sandbox's service list. The return
+value is an `httpx.Response`. `method` is the HTTP method, `path` is the service
+request path, `json` is an optional JSON body, and `headers` adds request headers.
+Transports without named service support raise `NotImplementedError`.
+
+The released 0.4.3 `Services` interface has `request()` only. Signed service URL
+creation is available in the [TypeScript Fleet client](/reference/sandbox-sdk/typescript#service-access);
+`create_signed_url()`, `list_signed_urls()`, and `revoke_signed_url()` are not
+part of this Python release.
+
+## Files
+
+Paths refer to the sandbox unless a parameter explicitly names a local path.
+These async methods use the connected computer-server file operations:
+
+| Method | Return type | Purpose |
+| --- | --- | --- |
+| `exists(path: str)` | `bool` | Tests whether a file exists |
+| `is_dir(path: str)` | `bool` | Tests whether a directory exists |
+| `size(path: str)` | `int` | Gets file size in bytes |
+| `list(path: str)` | `list[FileEntry]` | Lists directory entries |
+| `make_dir(path: str)` | `None` | Creates a directory |
+| `remove_dir(path: str)` | `None` | Removes a directory through the server |
+| `remove(path: str)` | `None` | Removes a file |
+| `read_text(path: str)` | `str` | Reads text |
+| `write_text(path: str, content: str)` | `None` | Writes text |
+| `read_bytes(path: str, offset=0, length=None)` | `bytes` | Reads bytes, with an optional byte range |
+| `write_bytes(path: str, content: bytes)` | `None` | Writes bytes |
+| `upload(local_path, remote_path: str)` | `None` | Copies a host file into the sandbox |
+| `download(remote_path: str, local_path)` | `None` | Copies a sandbox file to the host |
+
+Local paths accept `str` or `pathlib.Path`. `FileEntry` has `name: str`,
+`path: str`, `is_dir: bool`, and `size: int or None`.
+
+## Apps
+
+`await sb.apps.install(app_id: str)` and `await sb.apps.launch(app_id: str)`
+return `CommandResult`. They use the application catalog and guest installer;
+an application ID does not establish availability on every guest OS.
+
## Terminal
```python
@@ -145,7 +212,7 @@ async def scroll_down(x: int, y: int, distance: int = 600, duration_ms: int = 40
async def scroll_left(x: int, y: int, distance: int = 400, duration_ms: int = 300) -> None
async def scroll_right(x: int, y: int, distance: int = 400, duration_ms: int = 300) -> None
async def fling(x1: int, y1: int, x2: int, y2: int) -> None
-async def gesture(duration_ms: int = 400, steps: int = 0, *finger_paths) -> None
+async def gesture(*finger_paths: tuple[int, int], duration_ms: int = 400, steps: int = 0) -> None
# N-finger gesture via MT Protocol B sendevent. Each positional arg is (x,y) waypoints for one finger.
# steps=0 = auto (duration_ms // 20, min 5).
async def pinch_in(cx: int, cy: int, spread: int = 300, duration_ms: int = 400) -> None
diff --git a/docs/content/docs/reference/sandbox-sdk/meta.json b/docs/content/docs/reference/sandbox-sdk/meta.json
index d11948586d..fe87e5f7e1 100644
--- a/docs/content/docs/reference/sandbox-sdk/meta.json
+++ b/docs/content/docs/reference/sandbox-sdk/meta.json
@@ -1 +1 @@
-{ "title": "Sandbox SDK", "pages": ["index", "interfaces", "image"] }
+{ "title": "Sandbox SDK", "pages": ["index", "pool", "interfaces", "image", "typescript"] }
diff --git a/docs/content/docs/reference/sandbox-sdk/pool.mdx b/docs/content/docs/reference/sandbox-sdk/pool.mdx
new file mode 100644
index 0000000000..668cae2cf3
--- /dev/null
+++ b/docs/content/docs/reference/sandbox-sdk/pool.mdx
@@ -0,0 +1,157 @@
+---
+title: Pool and claim reference
+description: Python Fleet pool configuration, claim acquisition, cleanup, and resource types in cua-sandbox 0.4.3.
+---
+
+`Pool` and `Template` are exported by `cua_sandbox` 0.4.3. These APIs use Fleet
+credentials independently of the legacy `CUA_API_KEY` flow. See
+[configuration and authentication](/reference/sandbox-sdk#configuration-and-authentication).
+
+## Pool.apply
+
+Reconciles a named Fleet pool and its template from an `Image`:
+
+```python
+async def apply(
+ image: Image, *, name: str, replicas: int = 1,
+ cpu: int | None = None, memory_mb: int | None = None,
+ services: dict[str, int] | None = None,
+ autoscaling: WarmPoolAutoscaling | None = None,
+ ttl_seconds_after_created: int | None = None,
+) -> Pool: ...
+```
+
+| Parameter | Contract |
+| --- | --- |
+| `image` | Built-in or explicit registry image accepted by the [Fleet image constraints](/reference/sandbox-sdk/image#fleet-image-constraints) |
+| `name` | Required nonempty pool name; pool names are globally unique across accounts |
+| `replicas` | Desired pool replica count; default `1` |
+| `cpu`, `memory_mb` | Optional template CPU and memory overrides |
+| `services` | Mapping from service name to target port. If omitted or empty, uses `server: 8000` and `port-N: N` for exposed image ports other than 8000 |
+| `autoscaling` | Optional `WarmPoolAutoscaling` resource |
+| `ttl_seconds_after_created` | Optional pool expiry in seconds from creation |
+
+The method reconciles the pool, then its template. If template reconciliation
+fails, it attempts to delete the reconciled pool. A returned `Pool` holds the
+template reference so that `delete()` can remove both resources.
+
+## Pool lookup, reconciliation, and deletion
+
+These methods use the typed Fleet requests for explicit configuration:
+
+```python
+async def get(name: str) -> Pool: ...
+async def reconcile(request: CreatePoolRequest) -> Pool: ...
+async def delete(self) -> None: ...
+```
+
+`Pool.get()` retrieves an existing pool without reconciling its configuration.
+`Pool.reconcile()` requires a `CreatePoolRequest` instance and creates or
+reconciles the pool described by it. Both return a wrapper with `name: str` and
+`resource`, the underlying Fleet pool resource.
+
+`delete()` deletes the pool. It also deletes the owned template when called on
+the result of `Pool.apply()`. A wrapper returned by `get()` or `reconcile()` does
+not record template ownership; manage that template separately.
+
+`PoolAccessDeniedError` reports Fleet pool access denial. Choose a pool name
+owned by the authenticated account; an inaccessible name is not an invitation
+to overwrite another account's pool.
+
+## Pool.claim
+
+Returns an awaitable that also supports an async context manager:
+
+```python
+def claim(
+ self, *, spec: ClaimSpec | None = None, name: str | None = None,
+ service: str = "server", time_to_start: float | None = None,
+ ttl_seconds_after_created: int | None = None,
+): ...
+```
+
+| Parameter | Contract |
+| --- | --- |
+| `spec` | Optional typed claim specification |
+| `name` | Optional claim identity. If a matching claim exists in the pool namespace, reconnects to it; otherwise creates it |
+| `service` | Named service to connect to; default `"server"` |
+| `time_to_start` | Optional service readiness timeout in seconds, after claim binding |
+| `ttl_seconds_after_created` | Optional claim expiry in seconds from creation; cannot be combined with an explicit `spec` |
+
+`await pool.claim()` waits for binding and service readiness, then returns a
+connected `Sandbox`. Its caller must call `close()` to release the claim.
+`async with pool.claim()` calls `close()` on exit, including when it reuses a
+named claim. If acquisition fails, the SDK attempts to release a claim created
+by that acquisition; it does not release a preexisting claim on that path.
+
+`disconnect()` only drops the connection. It does not release the claim. See
+[Sandbox lifecycle and ownership](/reference/sandbox-sdk#lifecycle-and-ownership).
+
+## Pool.create_claim
+
+Creates a claim without waiting for binding or connecting a service:
+
+```python
+async def create_claim(
+ self, *, spec: ClaimSpec | None = None, name: str | None = None,
+ ttl_seconds_after_created: int | None = None,
+): ...
+```
+
+The returned handle has these members. Its concrete class is private; obtain it
+through `create_claim()` rather than importing the class.
+
+| Member | Contract |
+| --- | --- |
+| `namespace`, `name`, `pool_name`, `service` | Claim identity and selected service; default service is `"server"` |
+| `to_dict() -> dict[str, Any]` | Serializes identity for `Sandbox.from_dict()` |
+| `await wait(service=None, time_to_start=None) -> Sandbox` | Waits for binding and service readiness and connects |
+| `await renew(shutdown_time: str) -> None` | Updates the absolute shutdown timestamp |
+| `await release() -> None` | Deletes the claim; an already-missing claim is accepted |
+
+The caller owns cleanup after `create_claim()`, including when a later `wait()`
+fails. After connecting, `Sandbox.close()` releases the claim and disconnects.
+
+## Expiry and renewal
+
+The `ttl_seconds_after_created` convenience parameters accept integer values
+from `0` through `4294967295`, excluding booleans. `None` omits the field. The
+schema describes the field as a creation-age TTL; accepting a value at the
+client does not establish the server's expiry policy. Pool and claim TTLs are
+configured separately.
+When supplying an explicit `ClaimSpec`, set the TTL in that spec instead of
+passing the convenience parameter.
+
+`Sandbox.keep_alive(minutes=...)` updates the claim's absolute shutdown time.
+It does not reset the resource's creation timestamp. See
+[Expire pools and claims](/how-to-guides/sandbox/expire-pools-and-claims)
+for expiry configuration.
+
+## Template and resource types
+
+`Template.reconcile(request: CreateTemplateRequest)` is async and returns a
+wrapper with `name` and `resource`. `TemplateResource` is the underlying Fleet
+template type, distinct from the `Template` wrapper.
+
+The following types and their named builders are reexported by `cua_sandbox`:
+
+| Type | Main fields or purpose | Builder |
+| --- | --- | --- |
+| `CreatePoolRequest` | `namespace`, `spec` | `CreatePoolRequestBuilder` |
+| `CreateTemplateRequest` | `namespace`, `name`, `spec` | `CreateTemplateRequestBuilder` |
+| `SandboxTemplateRef` | Template `name` | `SandboxTemplateRefBuilder` |
+| `OsGymSandboxWarmPoolSpec` | `replicas`, `sandbox_template_ref`, `autoscaling`, `ttl_seconds_after_created` | `OsGymSandboxWarmPoolSpecBuilder` |
+| `WarmPoolAutoscaling` | `min_pool_size`, `initial_pool_size`, `max_pool_size` | `WarmPoolAutoscalingBuilder` |
+| `OsGymSandboxTemplateSpec` | `vm_template` | `OsGymSandboxTemplateSpecBuilder` |
+| `VmTemplate` | Container disk image, runtime, resources, firmware, and services | `VmTemplateBuilder` |
+| `SandboxService` | `name`, `target_port`, optional `protocol` | `SandboxServiceBuilder` |
+
+`ClaimSpec`, `RuntimeKind`, `Firmware`, and `ServiceProtocol` are also
+reexported. A `ClaimSpec` constructor requires keyword arguments
+`sandbox_template_ref`, `warmpool`, `bind_deadline`, and `lifecycle`, even when
+the latter three are `None`; `ttl_seconds_after_created` is optional. Builders
+provide named setters and `build()` for the types listed above.
+
+These bindings come from the published `cua-fleet` 0.1.14 dependency, imported
+as `fleet_sdk`. Type availability describes the client schema; it does not
+establish runtime or image support on a deployment.
diff --git a/docs/content/docs/reference/sandbox-sdk/typescript.mdx b/docs/content/docs/reference/sandbox-sdk/typescript.mdx
new file mode 100644
index 0000000000..56c888234c
--- /dev/null
+++ b/docs/content/docs/reference/sandbox-sdk/typescript.mdx
@@ -0,0 +1,152 @@
+---
+title: TypeScript Fleet reference
+description: Entry points, client methods, resource types, and lifecycle contracts for @trycua/fleet 0.1.1.
+---
+
+This page describes the published `@trycua/fleet` 0.1.1 package
+([npm version metadata](https://registry.npmjs.org/@trycua/fleet/0.1.1)).
+It provides Fleet resource operations through WebAssembly bindings.
+Its `Pool` and `Sandbox` exports are resource records, not the Python
+`Pool.apply()` and computer-control `Sandbox` classes.
+
+## Package and entry points
+
+The package is installed with:
+
+```bash
+npm install @trycua/[email protected]
+```
+
+Choose the entry point for the execution environment:
+
+| Import | Contract |
+| --- | --- |
+| `@trycua/fleet/node` | Loads the bundled WebAssembly file from disk; exports `FetchHttpClient` |
+| `@trycua/fleet/browser` | Loads WebAssembly in a browser; uses browser-compatible client construction |
+| `@trycua/fleet` | Package root has conditional exports; explicit `/node` or `/browser` avoids depending on resolver condition ordering |
+
+The package does not declare a Node.js `engines` range. Its Node HTTP adapter
+uses global `fetch` and `AbortSignal.timeout`; import availability alone does
+not establish compatibility with every Node.js release or browser bundler.
+
+## Initialization and authentication
+
+`uniffiInitAsync(): Promise<void>` initializes the WebAssembly bindings. Await it
+before using generated builders or client constructors. Repeated calls reuse
+the initialization promise.
+
+The Node entry point provides this helper:
+
+```ts
+declare function createFleetClient(
+ configuration: CyclopsTokenProviderConfiguration,
+ accessToken: string,
+): Promise<CyclopsClient>;
+```
+
+This helper initializes the bindings and constructs a client with a supplied
+bearer token. It does not read Python SDK environment variables or acquire a
+token. The browser entry point instead exposes
+`CyclopsClient.connectBrowserWithAccessToken(configuration, accessToken)` after
+`uniffiInitAsync()`. For credential acquisition, see
+[Fleet pools need their own credentials](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials).
+
+The token-based configuration has these fields:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `baseUrl` | `string` | Fleet API base URL |
+| `poolPollIntervalMs` | `bigint` | Pool polling interval in milliseconds |
+| `poolPollLimit` | `number` | Pool polling attempt limit |
+| `claimPollIntervalMs` | `bigint` | Claim polling interval in milliseconds |
+| `claimPollLimit` | `number` | Claim polling attempt limit |
+
+For explicit OAuth client credentials in Node, initialize the bindings and use
+`CyclopsClient.connect(configuration, new FetchHttpClient())`. Its
+`CyclopsConfiguration` adds `tokenUrl: string` and
+`credentials: CyclopsCredentials` to the polling and API fields above.
+`CyclopsCredentials` accepts the client ID and secret. Keep client secrets out
+of browser bundles; the browser entry point accepts a bearer token obtained by
+the application's authentication flow.
+
+## Client methods
+
+These methods belong to `CyclopsClientLike`, the interface implemented by the
+client. Each async method accepts a final optional `{ signal: AbortSignal }`
+argument. Types below use the exported TypeScript names.
+
+| Method | Return type | Contract |
+| --- | --- | --- |
+| `createPool(request: CreatePoolRequest)` | `Promise<Pool>` | Creates a pool |
+| `reconcilePool(request: CreatePoolRequest)` | `Promise<Pool>` | Creates or reconciles a pool |
+| `getPool(name: string)` | `Promise<Pool>` | Gets a named pool |
+| `listPools(namespace: string)` | `Promise<Pool[]>` | Lists pools in a namespace |
+| `updatePool(pool: Pool)` | `Promise<Pool>` | Updates a pool resource |
+| `deletePool(pool: Pool)` | `Promise<void>` | Deletes a pool |
+| `createTemplate(request: CreateTemplateRequest)` | `Promise<Template>` | Creates a template |
+| `reconcileTemplate(request: CreateTemplateRequest)` | `Promise<Template>` | Creates or reconciles a template |
+| `getTemplate(namespace: string, name: string)` | `Promise<Template>` | Gets a template |
+| `listTemplates(namespace: string)` | `Promise<Template[]>` | Lists templates |
+| `updateTemplate(template: Template)` | `Promise<Template>` | Updates a template |
+| `deleteTemplate(template: Template)` | `Promise<void>` | Deletes a template |
+| `createClaim(request: CreateClaimRequest)` | `Promise<Claim>` | Creates a claim without waiting for binding |
+| `getClaim(claim: Claim)` | `Promise<Claim>` | Refreshes a claim resource |
+| `listClaims(namespace: string)` | `Promise<Claim[]>` | Lists claims |
+| `waitClaim(claim: Claim)` | `Promise<Sandbox>` | Waits for binding and returns sandbox identity and services |
+| `renewClaim(claim: Claim, shutdownTime: string)` | `Promise<Claim>` | Updates the absolute shutdown time |
+| `deleteClaim(claim: Claim)` | `Promise<void>` | Releases a claim |
+
+The application owns cleanup. A returned `Sandbox` is a record; it has no
+Python-style `close()` or async context manager. Keep the `Claim` for
+`deleteClaim()`, and manage pool and template deletion separately. Renewal must
+occur before the shutdown deadline. `waitClaim()` establishes binding; it does
+not establish that an application service is ready.
+
+## Service access
+
+These operations address a service on a bound `Sandbox`:
+
+| Method | Return type |
+| --- | --- |
+| `serviceRequest(sandbox, service: string, path: string, request: HttpRequest)` | `Promise<HttpResponse>` |
+| `createSignedServiceUrl(request: CreateSignedServiceUrlRequest)` | `Promise<SignedServiceUrl>` |
+| `listSignedServiceUrls(sandbox: Sandbox)` | `Promise<SignedServiceUrl[]>` |
+| `revokeSignedServiceUrl(signedServiceUrl: SignedServiceUrl)` | `Promise<void>` |
+
+`HttpRequest` carries `method`, `url`, `headers`, optional `body`, and optional
+`timeoutSecs`. `HttpResponse` carries `status`, `headers`, and `body`. Headers
+are `{ name: string, value: string }[]`; bodies use `ArrayBuffer`, and
+`timeoutSecs` uses `bigint`.
+
+Signed URLs grant access to their selected service without a separate bearer
+header. See [Share a service with a signed URL](/how-to-guides/sandbox/share-service-with-signed-url)
+for creation, expiry, and revocation usage.
+
+## Resource types and builders
+
+Fleet records use camelCase field names:
+
+| Type | Fields |
+| --- | --- |
+| `ResourceMetadata` | `namespace`, `name`, optional `labels`, optional `creationTimestamp` |
+| `Pool`, `Template`, `Claim` | `apiVersion`, `kind`, `metadata`, `spec`; pools and claims also have optional `status` |
+| `Sandbox` | `namespace`, `claim`, `name`, `services` |
+| `CreatePoolRequest` | `namespace`, `spec: OsGymSandboxWarmPoolSpec` |
+| `CreateTemplateRequest` | `namespace`, `name`, `spec: OsGymSandboxTemplateSpec` |
+| `CreateClaimRequest` | `pool`, optional `spec: ClaimSpec`, optional `name` |
+| `CreateSignedServiceUrlRequest` | `sandbox`, `service`, `expiresInSeconds: number`, optional `label` |
+
+Builders include `CreatePoolRequestBuilder`, `CreateTemplateRequestBuilder`,
+`CreateClaimRequestBuilder`, `CreateSignedServiceUrlRequestBuilder`,
+`OsGymSandboxWarmPoolSpecBuilder`, `OsGymSandboxTemplateSpecBuilder`,
+`SandboxTemplateRefBuilder`, `VmTemplateBuilder`, `SandboxServiceBuilder`, and
+`WarmPoolAutoscalingBuilder`. Each has named setters and `build()`.
+
+Runtime and protocol values use `RuntimeKind`, `Firmware`, and
+`ServiceProtocol`. Availability in the schema does not guarantee deployment
+support. The exported `SdkError` variants include status/transport failures,
+`ClaimFailed`, `ClaimTimeout`, `PoolAccessDenied`, `UnknownService`, and
+`SignedServiceUrlsUnavailable`.
+
+For a complete provisioning example, see
+[Create a pool with TypeScript](/how-to-guides/sandbox/create-pool-with-typescript).