Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
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.mdxindex 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 temporaryaccess 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:```bashexport 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 beforereleasing 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 typescriptnpm pkg set type=module```@@ -231,9 +166,6 @@ The Fleet client manages signed URLs directly. Keep the returnedthe URL and namespace. The nested cleanup blocks revoke the URL, release theclaim, 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.mdxindex 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 referencedescription: "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 Imagedef 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/XFCEdef 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.mdxindex 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.mdxindex 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```pythonasync 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) -> Nonedef 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 |```pythonasync 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 = 40async def scroll_left(x: int, y: int, distance: int = 400, duration_ms: int = 300) -> Noneasync def scroll_right(x: int, y: int, distance: int = 400, duration_ms: int = 300) -> Noneasync 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) -> Nonediff --git a/docs/content/docs/reference/sandbox-sdk/meta.json b/docs/content/docs/reference/sandbox-sdk/meta.jsonindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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).