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: remove the Cua Fleets docs after the 16 Oct shutdown (#5398)

Francesco Bonaccic4ec0dd9272e
diff --git a/.github/scripts/sync_sdk_release_docs.py b/.github/scripts/sync_sdk_release_docs.py
index 5ff083e3f7..c16b1bbb3f 100644
--- a/.github/scripts/sync_sdk_release_docs.py
+++ b/.github/scripts/sync_sdk_release_docs.py
@@ -9,7 +9,7 @@ def main(argv: list[str] | None = None) -> int:
parser.add_argument("--from", dest="previous", required=True)
args = parser.parse_args(argv)
version = (args.root / "libs/cua/VERSION").read_text().strip()
- paths = [path for folder in ("cua-cli", "cua-sdk", "fleets")
+ paths = [path for folder in ("cua-cli", "cua-sdk")
for path in (args.root / "docs/content/docs" / folder).rglob("*.mdx")]
for path in [*paths, args.root / "scripts/docs-generators/cli-specs/cua.json"]:
content = path.read_text()
diff --git a/.github/scripts/tests/test_sync_sdk_release_docs.py b/.github/scripts/tests/test_sync_sdk_release_docs.py
index 493b2d0222..9cd8cbe78a 100644
--- a/.github/scripts/tests/test_sync_sdk_release_docs.py
+++ b/.github/scripts/tests/test_sync_sdk_release_docs.py
@@ -15,7 +15,7 @@ def test_sync_sdk_release_docs_updates_standalone_versions(tmp_path: Path):
)
paths = [
tmp_path / f"docs/content/docs/{folder}/nested/page.mdx"
- for folder in ("cua-cli", "cua-sdk", "fleets")
+ for folder in ("cua-cli", "cua-sdk")
]
paths.append(tmp_path / "scripts/docs-generators/cli-specs/cua.json")
outside = tmp_path / "docs/content/docs/other/page.mdx"
diff --git a/.github/workflows/ci-check-docs.yml b/.github/workflows/ci-check-docs.yml
index 7528e1aed3..d6cb78b859 100644
--- a/.github/workflows/ci-check-docs.yml
+++ b/.github/workflows/ci-check-docs.yml
@@ -23,11 +23,7 @@ on:
- "libs/cua/**"
- "docs/content/docs/cua-cli/reference/**"
- "docs/content/docs/cua-sdk/reference/**"
- # Fleets (libs/fleet mirror: client, swagger, Terraform provider) and
# Spaces (contract manifest) references.
- - "libs/fleet/**"
- - "docs/content/docs/fleets/reference/**"
- - "docs/content/docs/fleets/guides/**"
- "docs/content/docs/spaces/reference/**"
# The shared image catalog and the hand-written pages with generated
# catalog regions (scripts/docs-generators/sandbox.ts).
@@ -83,7 +79,7 @@ jobs:
- name: Test generator routing and ownership
run: |
node docs/node_modules/tsx/dist/cli.mjs scripts/docs-generators/runner.ts --test-routing
- node docs/node_modules/tsx/dist/cli.mjs --test scripts/docs-generators/runner.test.ts scripts/docs-generators/cua-driver.test.ts scripts/docs-generators/cua-driver-platform.test.ts scripts/docs-generators/sandbox.test.ts scripts/docs-generators/prose-style.test.ts scripts/docs-generators/lume.test.ts scripts/docs-generators/cua-cli.test.ts scripts/docs-generators/cli-mdx.test.ts scripts/docs-generators/cua-bench.test.ts scripts/docs-generators/reference-quality.test.ts scripts/docs-generators/cua-sdk.test.ts scripts/docs-generators/python-sdk.test.ts scripts/docs-generators/typescript-sdk.test.ts scripts/docs-generators/rust-crates.test.ts scripts/docs-generators/proto.test.ts scripts/docs-generators/fleet.test.ts scripts/docs-generators/spaces.test.ts
+ node docs/node_modules/tsx/dist/cli.mjs --test scripts/docs-generators/runner.test.ts scripts/docs-generators/cua-driver.test.ts scripts/docs-generators/cua-driver-platform.test.ts scripts/docs-generators/sandbox.test.ts scripts/docs-generators/prose-style.test.ts scripts/docs-generators/lume.test.ts scripts/docs-generators/cua-cli.test.ts scripts/docs-generators/cli-mdx.test.ts scripts/docs-generators/cua-bench.test.ts scripts/docs-generators/reference-quality.test.ts scripts/docs-generators/cua-sdk.test.ts scripts/docs-generators/python-sdk.test.ts scripts/docs-generators/typescript-sdk.test.ts scripts/docs-generators/rust-crates.test.ts scripts/docs-generators/proto.test.ts scripts/docs-generators/spaces.test.ts
- name: Select affected generator rows
id: scope
env:
@@ -91,7 +87,7 @@ jobs:
run: |
set -euo pipefail
if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
- GENERATORS="cua-driver lume cua-bench sandbox cua-cli cua-sdk cua-sdk-python cua-sdk-ts cua-rust cua-proto fleet spaces"
+ GENERATORS="cua-driver lume cua-bench sandbox cua-cli cua-sdk cua-sdk-python cua-sdk-ts cua-rust cua-proto spaces"
else
git diff --name-only HEAD^1 HEAD > "$RUNNER_TEMP/docs-changed-files.txt"
GENERATORS=$(node docs/node_modules/tsx/dist/cli.mjs scripts/docs-generators/runner.ts --changed-files-file "$RUNNER_TEMP/docs-changed-files.txt")
@@ -111,7 +107,7 @@ jobs:
"sandbox": [{"library": "sandbox", "platform": "linux", "os": "ubuntu-latest"}],
}
for library in ("cua-bench", "cua-cli", "cua-sdk", "cua-sdk-python", "cua-sdk-ts",
- "cua-rust", "cua-proto", "fleet", "spaces"):
+ "cua-rust", "cua-proto", "spaces"):
rows[library] = [{"library": library, "platform": "linux", "os": "ubuntu-latest"}]
selected = sys.argv[1].split()
unknown = sorted(set(selected) - set(rows))
@@ -144,7 +140,7 @@ jobs:
# in debug; with the restored cache that fills the hosted runner's disk
# ("No space left on device" linking libcua_spaces_ffi.a).
- name: Free disk space (cua SDK generators)
- if: runner.os == 'Linux' && contains(fromJSON('["cua-cli","cua-sdk","cua-rust","fleet"]'), matrix.library)
+ if: runner.os == 'Linux' && contains(fromJSON('["cua-cli","cua-sdk","cua-rust"]'), matrix.library)
run: |
sudo rm -rf /usr/local/lib/android /usr/share/dotnet /opt/ghc /opt/hostedtoolcache/CodeQL /usr/local/share/boost /usr/local/.ghcup || true
df -h /
@@ -178,23 +174,23 @@ jobs:
clang pkg-config libdbus-1-dev libpipewire-0.3-dev libspa-0.2-dev \
libei-dev libxkbcommon-dev libx11-dev libxi-dev libxtst-dev libxext-dev
- name: Install protoc (cua SDK generators)
- if: contains(fromJSON('["cua-cli","cua-sdk","cua-rust","fleet"]'), matrix.library)
+ if: contains(fromJSON('["cua-cli","cua-sdk","cua-rust"]'), matrix.library)
uses: ./.github/actions/setup-protoc
- name: Install pinned Rust toolchain (cua SDK generators)
- if: contains(fromJSON('["cua-cli","cua-sdk","cua-rust","fleet"]'), matrix.library)
+ if: contains(fromJSON('["cua-cli","cua-sdk","cua-rust"]'), matrix.library)
uses: dtolnay/[email protected]
- name: Install the pinned nightly for rustdoc JSON (this job only)
if: matrix.library == 'cua-rust'
run: rustup toolchain install nightly-2026-09-20 --profile minimal
- uses: Swatinem/rust-cache@9d47c6ad4b02e050fd481d890b2ea34778fd09d6 # v2
- if: contains(fromJSON('["cua-cli","cua-sdk","cua-rust","fleet"]'), matrix.library)
+ if: contains(fromJSON('["cua-cli","cua-sdk","cua-rust"]'), matrix.library)
with:
workspaces: |
libs/cua
scripts/docs-generators/rustdoc-json
key: docs-${{ matrix.library }}
- name: Install Linux build dependencies (cua SDK)
- if: contains(fromJSON('["cua-cli","cua-sdk","cua-rust","fleet"]'), matrix.library)
+ if: contains(fromJSON('["cua-cli","cua-sdk","cua-rust"]'), matrix.library)
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends \
diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
index bab4a2e646..c6ac2cd81a 100644
--- a/.github/workflows/release-please.yml
+++ b/.github/workflows/release-please.yml
@@ -295,7 +295,7 @@ jobs:
python3 .github/scripts/sync_sdk_release_docs.py --from "$PREVIOUS"
SDK_LOCKS=$(python3 .github/scripts/sync_sdk_release_locks.py)
python3 .github/scripts/validate_release_versions.py --product sdk
- git add docs/content/docs/cua-cli docs/content/docs/cua-sdk docs/content/docs/fleets scripts/docs-generators/cli-specs/cua.json
+ git add docs/content/docs/cua-cli docs/content/docs/cua-sdk scripts/docs-generators/cli-specs/cua.json
if [[ -n "$SDK_LOCKS" ]]; then
mapfile -t SDK_LOCK_PATHS <<< "$SDK_LOCKS"
git add -- "${SDK_LOCK_PATHS[@]}"
diff --git a/docs/content/docs/cua-sdk/concepts/how-sandboxes-work.mdx b/docs/content/docs/cua-sdk/concepts/how-sandboxes-work.mdx
index 2a7d841fe2..5d48804db4 100644
--- a/docs/content/docs/cua-sdk/concepts/how-sandboxes-work.mdx
+++ b/docs/content/docs/cua-sdk/concepts/how-sandboxes-work.mdx
@@ -81,7 +81,7 @@ a sandbox; deleting destroys it and its state.
| `suspend` / `resume` | Local only |
| Direct sandbox | Deleting only forgets the record |
-The SDK manages cloud capacity for your account; to manage it yourself, see
-[Cua Fleets](/fleets). `Sandbox.snapshot()` is not available in
+The SDK managed cloud capacity for your account until Cua Cloud
+[ended on 16 October 2026](/cua-sdk/guides/cua-cloud-ended). `Sandbox.snapshot()` is not available in
`cua-sandbox` 0.9.0. Streaming, teleport and the other
[Spaces](/spaces) primitives need cua-spacesd.
diff --git a/docs/content/docs/cua-sdk/guides/cloud.mdx b/docs/content/docs/cua-sdk/guides/cloud.mdx
index 397f1708ad..d4e818b7cc 100644
--- a/docs/content/docs/cua-sdk/guides/cloud.mdx
+++ b/docs/content/docs/cua-sdk/guides/cloud.mdx
@@ -5,6 +5,12 @@ description: Run the same sandbox code in the Cua cloud, make the cloud your def
import { Callout } from 'fumadocs-ui/components/callout';
+<Callout type="warn" title="Cua Cloud ended on 16 October 2026">
+ `on="cloud"` and `local=False` no longer reach a service. Run sandboxes
+ locally or in [your own cloud](/cua-sdk/guides/your-cloud). See
+ [Cua Cloud (Fleets) has ended](/cua-sdk/guides/cua-cloud-ended).
+</Callout>
+
Cloud sandboxes use the same code as local ones with `on="cloud"` (`local=False`
in cua-sandbox), and `--on cloud` in the CLI. To run in your own AWS, Google
Cloud or Modal account instead, see [Use your own cloud](/cua-sdk/guides/your-cloud). The SDK manages the capacity:
@@ -64,7 +70,7 @@ In code, pass `local=False` to the [quickstart](/cua-sdk/quickstart) calls, and
| `warm` | on for the canonical images (`CUA_FLEET_WARM`) | Keep one ready sandbox of this image |
| `max_pool_size` | `10` (`CUA_FLEET_MAX_POOL_SIZE`) | Autoscaling ceiling |
| `claim_ttl` | 15 min (`CUA_FLEET_CLAIM_TTL`) | Lifetime after your process stops renewing |
-| `pool` | none | Claim from a pool you manage ([Cua Fleets](/fleets/guides/capacity-and-claims)) |
+| `pool` | none | Claim from a pool you manage (Cua Fleets, [ended 16 Oct 2026](/cua-sdk/guides/cua-cloud-ended)) |
`cpu` and `memory` are part of the shape: a new shape is a new pool. Managed
pools idle for 30 minutes are deleted (`CUA_FLEET_POOL_IDLE_GC`, `off` disables
@@ -122,7 +128,7 @@ run `cua auth login` or `cua config set default.on local`.
- A cold image's first start takes a few minutes; canonical images are warm.
- Services go through the gateway: `url()` is a signed URL and `request` adds
the gateway's credentials.
-- `command=`, `env=` and [sidecars](/fleets/guides/sidecars) work on container
+- `command=`, `env=` and [sidecars](/cua-sdk/guides/sidecars) work on container
and VM images; VM `env` values are single-line.
- The sandbox lapses `claim_ttl` after your process stops renewing it
([Lifecycle](/cua-sdk/guides/lifecycle#cloud-lifetime)). No suspend or
@@ -132,9 +138,8 @@ run `cua auth login` or `cua config set default.on local`.
<Callout type="info">
Image builds from layers are not in the cloud yet: a cloud sandbox with
layers fails with a clear error. Build locally, push, and reference the
- image ([Fleet images](/fleets/guides/images)).
+ image ([Choose and build an image](/cua-sdk/guides/images)).
</Callout>
-For named pools, fixed warm replicas, Terraform or per-claim secrets, use
-[Cua Fleets](/fleets). For errors such as `401` or `403`, see
-[Troubleshoot](/fleets/guides/troubleshoot).
+Named pools, fixed warm replicas, Terraform and per-claim secrets were part of
+Cua Fleets, which [ended on 16 October 2026](/cua-sdk/guides/cua-cloud-ended).
diff --git a/docs/content/docs/cua-sdk/guides/cua-cloud-ended.mdx b/docs/content/docs/cua-sdk/guides/cua-cloud-ended.mdx
new file mode 100644
index 0000000000..59cf4e05cf
--- /dev/null
+++ b/docs/content/docs/cua-sdk/guides/cua-cloud-ended.mdx
@@ -0,0 +1,33 @@
+---
+title: Cua Cloud (Fleets) has ended
+description: Cua Cloud and Cua Fleets stopped on 16 October 2026. What changed, what happened to your data, and where to run sandboxes now.
+---
+
+Cua Cloud, including Cua Fleets (pools, claims, warm replicas and the Terraform
+provider), stopped on Friday 16 October 2026. Remaining customer data was
+deleted then. The Fleets pages that used to be here have been removed.
+
+## What still works
+
+The same SDK calls, images and `cua` CLI commands run anywhere else:
+
+| Where | How | Guide |
+| --- | --- | --- |
+| This machine | `Sandbox.create(...)` (the default), `cua sb create` | [Set up local runtimes](/cua-sdk/guides/local-runtimes) |
+| Your own AWS, Google Cloud or Modal account | `on="aws"`, `on="gcp"`, `on="modal"`; `--on aws` in the CLI | [Use your own cloud](/cua-sdk/guides/your-cloud) |
+| A machine you run, shared with your team and agents | Cua Spaces | [Cua Spaces](/spaces) |
+
+## In your code
+
+- `on="cloud"`, `local=False`, `--on cloud`, `Cua.fleet()` and `cua fleet` are
+ deprecated and no longer reach a service. They are removed in `cua` 0.5.0.
+- Replace `on="cloud"` with a local runtime or your own cloud. Sidecars,
+ services, secrets and images work the same way there:
+ [Sidecars](/cua-sdk/guides/sidecars), [Services](/cua-sdk/guides/services),
+ [Secrets](/cua-sdk/guides/secrets), [Images](/cua-sdk/guides/images).
+- Fleet pool names, claim TTLs and warm-replica settings have no replacement.
+ Your own cloud gives each sandbox a time limit and cleans up after it
+ ([Time limits and cleanup](/cua-sdk/guides/your-cloud#time-limits-and-cleanup)).
+
+Questions: [GitHub issues](https://github.com/trycua/cua/issues) or
+[Discord](https://discord.com/invite/mVnXXpdE85).
diff --git a/docs/content/docs/cua-sdk/guides/images.mdx b/docs/content/docs/cua-sdk/guides/images.mdx
index 5f9638f0bb..8eb6f2c623 100644
--- a/docs/content/docs/cua-sdk/guides/images.mdx
+++ b/docs/content/docs/cua-sdk/guides/images.mdx
@@ -61,7 +61,7 @@ Each builder method returns a new, immutable `Image`. Locally, steps build
into your container engine before boot (VM images apply them after boot
through cua-spacesd). In the cloud, `apt_install`, `pip_install`, `uv_install`,
`run`, `copy` and `env` build remotely; until the cloud builds images, build
-and push it yourself ([Fleet images](/fleets/guides/images)).
+and push it yourself with [`cua image build` and `cua image push`](/cua-cli/reference/cli/image).
```python test="docs" id="install-packages" session="build"
from cua_sandbox import Image
diff --git a/docs/content/docs/cua-sdk/guides/lifecycle.mdx b/docs/content/docs/cua-sdk/guides/lifecycle.mdx
index a8121b96c5..0ae3392b57 100644
--- a/docs/content/docs/cua-sdk/guides/lifecycle.mdx
+++ b/docs/content/docs/cua-sdk/guides/lifecycle.mdx
@@ -90,8 +90,7 @@ await sb.keep_alive(minutes=60)
- With `cua daemon` running, CLI-created cloud sandboxes keep being renewed
after the command exits.
-Local sandboxes run until you delete them. For pool and claim TTLs, see
-[Capacity and claims](/fleets/guides/capacity-and-claims#expiry).
+Local sandboxes run until you delete them.
## Run many at once
diff --git a/docs/content/docs/cua-sdk/guides/meta.json b/docs/content/docs/cua-sdk/guides/meta.json
index 49e169fded..fa250a3811 100644
--- a/docs/content/docs/cua-sdk/guides/meta.json
+++ b/docs/content/docs/cua-sdk/guides/meta.json
@@ -11,6 +11,7 @@
"spacesd",
"local-runtimes",
"disk-usage",
+ "cua-cloud-ended",
"cloud",
"your-cloud",
"your-cloud-resources",
diff --git a/docs/content/docs/cua-sdk/guides/secrets.mdx b/docs/content/docs/cua-sdk/guides/secrets.mdx
index 95c1f0d989..f0835d0c5c 100644
--- a/docs/content/docs/cua-sdk/guides/secrets.mdx
+++ b/docs/content/docs/cua-sdk/guides/secrets.mdx
@@ -16,7 +16,6 @@ the cloud.
| Key files | A temporary file that is removed when the process exits (below) |
| Registry credentials | A [`RegistrySecret`](/cua-sdk/guides/images#private-registries), never logged or saved |
| Non-sensitive settings | `Image.env()`, `env=` on `Sandbox.create`, `Container(env=...)` |
-| A per-claim token on a Fleet pool | [Claim secrets](/fleets/guides/claim-secrets) |
## Environment variables
diff --git a/docs/content/docs/cua-sdk/reference/runtime-support.mdx b/docs/content/docs/cua-sdk/reference/runtime-support.mdx
index 435408a584..08f96674a6 100644
--- a/docs/content/docs/cua-sdk/reference/runtime-support.mdx
+++ b/docs/content/docs/cua-sdk/reference/runtime-support.mdx
@@ -69,7 +69,7 @@ disk, so pass `os_type='windows', kind='vm'` for a Windows containerDisk.
Cloud layers fail with a clear error until Fleet builds images. `cua image build` and `cua image push` build and
publish an image both sides can use. See
-[Build and publish an image](/fleets/guides/images).
+[Choose and build an image](/cua-sdk/guides/images).
## Workloads, ports and sidecars
diff --git a/docs/content/docs/fleets/guides/capacity-and-claims.mdx b/docs/content/docs/fleets/guides/capacity-and-claims.mdx
deleted file mode 100644
index baf4fe6df1..0000000000
--- a/docs/content/docs/fleets/guides/capacity-and-claims.mdx
+++ /dev/null
@@ -1,195 +0,0 @@
----
-title: Create capacity and claim from it
-description: Apply a named pool, claim sandboxes from it, keep a sandbox across processes, and bound lifetimes with TTLs.
----
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-`Sandbox.create(image, local=False)` needs no pool. Create one when you want a
-fixed name that other processes or teams claim from, a static warm size, a
-creation-age TTL, or Terraform ([Terraform](/fleets/guides/terraform)). Pool
-names are lowercase DNS labels, unique across all accounts.
-
-## Create a pool
-
-<Tabs groupId="language" persist items={['Python', 'TypeScript']}>
- <Tab value="Python">
-
-```python test="docs,fleet" id="create-pool" session="script" prelude="fakefleet,pool-name"
-import os
-
-from cua_sandbox import Image, Pool, PoolOptions, SandboxSpec
-
-pool = await Pool.apply(
- os.environ["CUA_POOL_NAME"],
- SandboxSpec(image=Image.linux(), cpu=4, memory_mb=4096, services={"env": 3211}),
- PoolOptions(replicas=1),
-)
-print(f"Pool ready to claim from: {pool.name}")
-```
-
- </Tab>
- <Tab value="TypeScript">
-
-```ts title="create-fleet-capacity.ts" test="docs" id="create-pool-typescript" prelude="fakefleet,pool-name"
-import { embedded, Pool, poolOptions, sandboxSpec } from '@trycua/cua';
-
-const fleet = embedded().fleet();
-const pool = await Pool.apply(
- fleet,
- process.env.CUA_POOL_NAME!,
- sandboxSpec('ghcr.io/trycua/linux:24.04', { cpu: 4, memoryMb: 4096, services: { env: 3211 } }),
- poolOptions({ runtime: 'gvisor', replicas: 1 })
-);
-await fleet.waitPoolReady(pool.name, 15 * 60_000);
-console.log(`Pool ready to claim from: ${pool.name}`);
-```
-
- </Tab>
-</Tabs>
-
-`Pool.apply` creates or updates the pool and its template. `SandboxSpec` is
-what the sandboxes run; `PoolOptions` is how capacity is kept
-([Pool reference](/cua-sdk/reference/python/pool)). `PoolAccessDeniedError`
-(`403`) usually means another account owns the name.
-
-## Claim from it
-
-A pool fixes the image, command, services and size, so pass only the pool:
-
-<Tabs groupId="language" persist items={['CLI', 'Python', 'TypeScript']}>
- <Tab value="CLI">
-
-```bash test="cli-shape" id="cua-sb-create"
-cua sb create --on cloud --pool my-team-desktop --name my-task
-cua sb exec my-task uname -a
-cua sb rm -f my-task
-```
-
- </Tab>
- <Tab value="Python">
-
-```python test="docs,fleet" id="claim-python" prelude="fakefleet,team-pool"
-from cua_sandbox import CloudOptions, Sandbox
-
-async with Sandbox.ephemeral(cloud=CloudOptions(pool="my-team-desktop")) as sb:
- print((await sb.shell.run("uname -a")).stdout.strip())
-```
-
- </Tab>
- <Tab value="TypeScript">
-
-```ts test="docs,fleet" id="claim-typescript" prelude="fakefleet,team-pool"
-import { CloudOptions, embedded, SandboxCreateOptions } from '@trycua/cua';
-
-const cua = embedded({ fleetFromSession: true });
-const sb = await cua.sandboxes().create(
- SandboxCreateOptions.create({
- on: 'cloud',
- image: '',
- cloud: CloudOptions.create({ pool: 'my-team-desktop' }),
- })
-);
-try {
- const out = await (await sb.spacesd(undefined)).sh('uname -a', undefined);
- console.log(new TextDecoder().decode(out.stdout).trim());
-} finally {
- await sb.delete_(); // releases the sandbox; the pool stays
-}
-```
-
- </Tab>
-</Tabs>
-
-Fields you pass with a pool must match its template, else `PoolSpecMismatch`
-shows the diff; `CloudOptions(pool=..., apply=True)` (CLI `--apply`) writes
-them to the template instead. A released sandbox may be recycled, so copy
-results out first.
-
-### Claim calls
-
-| Call | Behavior |
-| --- | --- |
-| `async with pool.claim(name=None, service="env")` | Reattaches to claim `name` if it exists, else creates one; waits for `service`; releases on exit |
-| `await pool.claim()` | A connected `Sandbox`: `close()` releases it, `disconnect()` keeps the claim |
-| `await pool.create_claim(name=None)` | Creates without waiting. The handle has `wait()`, `renew(shutdown_time)`, `release()` and `to_dict()` (for `Sandbox.from_dict`); you own cleanup |
-| `await Pool.check(name, spec)` | Raises `PoolSpecMismatch` when the set fields of `spec` differ from the template |
-| `await Pool.apply_template(name, spec)` | Writes those fields to the template; the pool keeps its capacity |
-
-A failed claim releases a claim it created, never a preexisting one. Images
-without cua-spacesd pass their own `service=`.
-
-## Keep a sandbox across processes
-
-Name the sandbox, do not release it, and extend its lease for idle periods
-(TypeScript: `sb.keepAlive(...)`, `sb.detach()`, `sandboxes().connect(name)`):
-
-```python test="docs" id="keep-python" session="keep" prelude="fakefleet,image"
-sb = await Sandbox.create(image, local=False, name="my-task", keep_alive_minutes=120)
-reference = sb.to_dict() # store it (JSON-serializable)
-await sb.disconnect() # the sandbox stays held
-
-sb = await Sandbox.from_dict(reference) # later, in another process
-await sb.keep_alive(minutes=120)
-await sb.close() # releases it
-```
-
-```bash test="cli-shape" id="cua-sb-keep-alive-my-task"
-cua sb keep-alive my-task --for 2h
-cua sb info my-task
-```
-
-## Expiry
-
-| Deadline | Applies to | Set with | Renewed? |
-| --- | --- | --- | --- |
-| Sandbox TTL | Every cloud sandbox | `CloudOptions(claim_ttl=...)`, `--claim-ttl`; `keep_alive` | Yes, while a process holds it |
-| Creation-age TTL | Your pools and their claims | `ttl_seconds_after_created=` | No, counts from creation |
-| Idle TTL | Your pools | `PoolOptions(idle_ttl=...)` | Deletes the pool after this long without claims |
-
-```python test="docs" id="claim-ttl" session="ttl" prelude="fakefleet"
-from cua_sandbox import CloudOptions, Image, Sandbox
-
-sb = await Sandbox.create(Image.linux(), cloud=CloudOptions(claim_ttl=30 * 60))
-await sb.keep_alive(minutes=120) # an absolute shutdown time two hours from now
-```
-
-```python test="docs" id="pool-ttl" session="pool" prelude="fakefleet,pool-vars"
-pool = await Pool.apply(
- Image.from_registry(IMAGE),
- name=POOL_NAME,
- replicas=1,
- ttl_seconds_after_created=86400, # the pool deletes itself after 24 hours
-)
-async with pool.claim(name=CLAIM_NAME, ttl_seconds_after_created=3600) as sb:
- ...
-```
-
-- Reapplying a pool or reconnecting to a named claim does not reset a
- creation-age TTL, so a rerun can expire soon after it starts.
-- A pool that expires deletes its sandboxes too. Keep its TTL longer than the
- work, and copy results out first.
-- In TypeScript set `poolTtlSeconds` in `poolOptions({...})`; in Terraform,
- `ttl_seconds_after_created` on `fleets_pool`.
-
-## Delete a pool
-
-Delete it after its users have released their sandboxes. Deleting removes its
-template and remaining sandboxes; deletion is asynchronous.
-
-<Tabs groupId="language" persist items={['Python', 'TypeScript']}>
- <Tab value="Python">
-
-```python test="docs" id="delete" session="delete" prelude="fakefleet,pool-applied"
-await pool.delete() # the Pool from Pool.apply() also deletes its template
-```
-
- </Tab>
- <Tab value="TypeScript">
-
-```ts test="docs" id="delete-typescript" prelude="fakefleet,pool-applied"
-await fleet.deletePool(POOL_NAME);
-```
-
- </Tab>
-</Tabs>
diff --git a/docs/content/docs/fleets/guides/claim-secrets.mdx b/docs/content/docs/fleets/guides/claim-secrets.mdx
deleted file mode 100644
index 1cdd4d2fd1..0000000000
--- a/docs/content/docs/fleets/guides/claim-secrets.mdx
+++ /dev/null
@@ -1,59 +0,0 @@
----
-title: Deliver per-claim secrets
-description: Give each claim of a warm pool its own cua-spacesd token, delivered into the sandbox when the claim binds.
----
-
-A warm replica boots before anyone claims it, so it cannot be built with a
-secret meant for one claimant. Claim secrets close that gap: when a claim
-binds, Fleet delivers a Secret into the already-running sandbox, and the guest
-reads it at `/run/cua/env-token`. cua-spacesd uses that file as its env token,
-so each claim gets its own token, which never crosses the network to the guest.
-
-## Enable it on the pool
-
-Set `claim_secrets=True` in the pool's `SandboxSpec` (Terraform:
-`claim_secrets = true` on `fleets_pool`). The image must run cua-spacesd, which
-waits for the token file before it accepts calls.
-
-## Claim with a token
-
-```python test="docs" id="claim-token" session="claim-token" prelude="fakefleet,pool-name"
-import os
-
-from cua_sandbox import Image, Pool, PoolOptions, SandboxSpec, generate_claim_token
-
-pool = await Pool.apply(
- os.environ["CUA_POOL_NAME"],
- SandboxSpec(image=Image.linux(), services={"env": 3211}, claim_secrets=True),
- PoolOptions(replicas=1),
-)
-token = generate_claim_token() # 64 hex characters from the OS RNG
-async with pool.claim(claim_token=token) as sb:
- print((await sb.shell.run("uname -a")).stdout.strip())
-await pool.delete()
-```
-
-The SDK writes the Secret `cua-claim-<claim>` (key `env-token`), creates the
-claim against it, and waits until spacesd answers with the token.
-
-| Language | Call |
-| --- | --- |
-| Python | `generate_claim_token()`, `pool.claim(claim_token=...)` |
-| TypeScript | `fleetGenerateClaimToken()`, `fleet.acquireWith(pool, options)` with `claimToken` set |
-| Rust | `fleet_generate_claim_token()`, `Fleet::acquire_with(pool, options)` with `claim_token` set |
-
-A token is 16 to 4096 characters of the bearer-token alphabet
-(`A-Z a-z 0-9 - . _ ~ + / =`); the SDK rejects one spacesd would refuse.
-
-## When the token does not arrive
-
-Delivery is asynchronous (about 40 seconds on gVisor). The
-claim waits at most 90 seconds after it binds. If spacesd still reports
-`awaiting token`, the SDK releases the claim and raises
-`ClaimSecretsNotDelivered` (`CuaError.ClaimSecretsNotDelivered` in the other
-bindings). Check that the pool has `claim_secrets` enabled and that the image's
-cua-spacesd reads `/run/cua/env-token`.
-
-The Secret belongs to the claim: releasing the claim deletes it. Other
-credentials your workload needs still go in at runtime
-([Pass secrets into a sandbox](/cua-sdk/guides/secrets)).
diff --git a/docs/content/docs/fleets/guides/images.mdx b/docs/content/docs/fleets/guides/images.mdx
deleted file mode 100644
index ce68bc5ed4..0000000000
--- a/docs/content/docs/fleets/guides/images.mdx
+++ /dev/null
@@ -1,93 +0,0 @@
----
-title: Publish a Fleet image
-description: Which runtime boots a cloud image, and how to build, push and reference your own image with cua image build.
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-
-A cloud sandbox boots an OCI artifact from a registry: the same reference you
-run locally. The runtime follows the artifact:
-
-| Artifact | Cloud runtime | Local runtime |
-| --- | --- | --- |
-| Container rootfs (any OCI image) | `gvisor` pod | Docker or Podman, gVisor when installed |
-| containerDisk (qcow2 at `/disk/disk.img`) | `kubevirt` VM | QEMU |
-| macOS (Lume) | Not offered | Lume |
-
-The canonical images publish both forms (`linux:24.04` and `linux:24.04-disk`)
-and one resolver picks the one a runtime needs, pinned by digest. Set the
-runtime yourself with `runtime="kubevirt"` (or `kind="vm"`) or `--runtime`; the
-SDK rejects a pairing the image cannot run (`InvalidPlacement`) before it
-creates anything.
-
-- The cloud runs amd64, so the image needs an amd64 variant.
-- Managed capacity is keyed by image digest and shape: two images never share
- replicas. Pin a digest when every sandbox must boot the same content.
-- A Windows containerDisk needs `os_type="windows"` (EFI firmware).
-
-For small changes (packages, files, env), add layers to an `Image`
-([Choose and build an image](/cua-sdk/guides/images)). Build and publish your
-own image for a VM disk, a pinned artifact your team shares, or while cloud
-builds from layers are not available. This uses the `cua` 0.4.1 CLI.
-
-## 1. Describe the image
-
-`cua image build` takes an `images.cua.ai/v1alpha1` Image resource. Layer types
-are `apt_install`, `pip_install`, `uv_install`, `app_install` and `run`; `env`
-and `ports` are recorded in the image. Keep secrets out of it.
-
-```json title="image.json" test="config" id="json-config" schema="cua-image"
-{
- "apiVersion": "images.cua.ai/v1alpha1",
- "kind": "Image",
- "metadata": { "name": "my-workspace", "namespace": "my-workspace" },
- "spec": {
- "recipe": {
- "osType": "linux",
- "distro": "ubuntu",
- "version": "24.04",
- "kind": "vm",
- "layers": [
- { "type": "apt_install", "packages": ["curl", "git"] },
- { "type": "run", "command": "mkdir -p /opt/app" }
- ],
- "env": { "APP_ENV": "production" },
- "ports": [8080]
- }
- }
-}
-```
-
-## 2. Build and push
-
-```bash test="cli-shape" id="cua-image-build"
-# containerDisk for VMs: KubeVirt and local QEMU (boots the base VM, applies layers over SSH)
-cua image build image.json --base vm:ghcr.io/trycua/linux:24.04-disk \
- --push ghcr.io/<you>/my-workspace:1.0-disk
-
-# rootfs for containers: gVisor in the cloud, Docker locally
-cua image build image.json --base container:ghcr.io/trycua/linux:24.04 \
- --push ghcr.io/<you>/my-workspace:1.0
-```
-
-The build prints `<reference>@sha256:<digest>`. It produces an image for the
-host architecture, so build cloud images on an x86_64 host. Registry
-credentials come from `CUA_REGISTRY_USERNAME` / `CUA_REGISTRY_PASSWORD`,
-`GITHUB_TOKEN` for `ghcr.io`, or your Docker config.
-
-<Callout type="warn">
- The cloud must be able to pull the image. A new GHCR package is private; make
- it public or pass a [registry secret](/cua-sdk/guides/images#private-registries).
- A pushed image carries everything on its disk.
-</Callout>
-
-## 3. Reference it
-
-```bash test="cli-shape" id="cua-sb-create"
-cua sb create ghcr.io/<you>/my-workspace:1.0 --name ws # local container
-cua sb create ghcr.io/<you>/my-workspace:1.0 --on cloud --name ws-cloud
-```
-
-In code, pass the digest to `Image.from_registry(...)`.
-`cua image create --file image.json` submits the same resource for a remote
-build where the deployment supports it.
diff --git a/docs/content/docs/fleets/guides/meta.json b/docs/content/docs/fleets/guides/meta.json
deleted file mode 100644
index 3893435a21..0000000000
--- a/docs/content/docs/fleets/guides/meta.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
- "title": "Guides",
- "pages": [
- "capacity-and-claims",
- "warm-pools",
- "terraform",
- "images",
- "sidecars",
- "claim-secrets",
- "troubleshoot"
- ]
-}
diff --git a/docs/content/docs/fleets/guides/sidecars.mdx b/docs/content/docs/fleets/guides/sidecars.mdx
deleted file mode 100644
index 086dccb49c..0000000000
--- a/docs/content/docs/fleets/guides/sidecars.mdx
+++ /dev/null
@@ -1,61 +0,0 @@
----
-title: Add sidecars on Fleet
-description: Put sidecar containers in a pool's template, and how Fleet runs them next to container and VM sandboxes.
----
-
-Sidecars are extra containers next to a sandbox, reached by name: the sandbox
-reaches `db:6379`, a sidecar reaches the sandbox at `main`. The API is the same
-locally and in the cloud ([Add sidecar containers](/cua-sdk/guides/sidecars));
-this page covers what Fleet does with them.
-
-## In a pool template
-
-Sidecars are part of a pool's `SandboxSpec`, so every claim gets them:
-
-```python test="docs" id="pool-sidecars" prelude="fakefleet,pool-name"
-import os
-
-from cua_sandbox import Container, Image, Pool, PoolOptions, SandboxSpec, tcp
-
-pool = await Pool.apply(
- os.environ["CUA_POOL_NAME"],
- SandboxSpec(
- image=Image.from_registry("python:3.12-slim"),
- command=["sleep", "infinity"],
- sidecars=[Container("redis:7-alpine", ports=[6379], name="db")],
- services={"db": 6379},
- wait_for=tcp("db"),
- ),
- PoolOptions(replicas=1),
-)
-await pool.delete()
-```
-
-`Sandbox.create(..., sidecars=[...], local=False)` does the same on a managed
-pool. Sidecars passed with `CloudOptions(pool=...)` are compared with the
-template like other fields (`PoolSpecMismatch` on a difference).
-
-## How Fleet runs them
-
-| Sandbox | Sidecars run in | Name resolution |
-| --- | --- | --- |
-| Container image (gVisor) | The sandbox's pod | By name or `localhost` |
-| VM image (KubeVirt) | A companion gVisor pod | The guest's `/etc/hosts` names each sidecar (Linux with cloud-init); only declared `ports` are reachable |
-| VM without cloud-init (Windows) | A companion gVisor pod | `<sandbox>-sidecars.<namespace>.svc.cluster.local` |
-
-`runtime="runc"` is a local setting; the cloud ignores it.
-
-## Limits
-
-- At most 8 sidecars per sandbox.
-- With sidecars, the service names `main`, `sidecars` and `sc` are reserved;
- a service with one of them is rejected.
-- A private sidecar image on the sandbox image's registry uses the same
- registry secret, on both runtimes.
-
-## Terraform
-
-`cua fleet pool export NAME --terraform` writes each sidecar as a `sidecar {}`
-block of `fleets_pool` (`name`, `image`, `args`, `ports`, `cpu`, `memory`).
-Those blocks need a `trycua/fleets` provider newer than 0.3.0
-([Terraform](/fleets/guides/terraform#export-an-existing-pool)).
diff --git a/docs/content/docs/fleets/guides/terraform.mdx b/docs/content/docs/fleets/guides/terraform.mdx
deleted file mode 100644
index fd7bd82573..0000000000
--- a/docs/content/docs/fleets/guides/terraform.mdx
+++ /dev/null
@@ -1,133 +0,0 @@
----
-title: Manage pools with Terraform
-description: Declare Linux and Windows Fleet pools as fleets_pool resources, apply them, and export existing pools to Terraform.
----
-
-Each pool is a `fleets_pool` resource of the public `trycua/fleets` provider.
-Claim from it with `cua sb create --on cloud --pool NAME` or
-`Sandbox.create(cloud=CloudOptions(pool=NAME))`. The examples pin provider
-`0.2.0`; for OpenTofu, run the same commands with `tofu`.
-
-## Authentication
-
-The provider has its own variables; `cua auth login`, `CUA_CLIENT_ID` and
-`FLEETS_TOKEN` do not configure it. Use an API key from
-`cua auth keys create NAME` ([credentials](/cua-sdk/guides/cloud#credentials)):
-
-```bash skip="placeholder"
-export CYCLOPS_ENDPOINT="https://run.cua.ai"
-export CYCLOPS_CLIENT_ID="<your-client-id>"
-export CYCLOPS_CLIENT_SECRET="<your-client-secret>"
-export CYCLOPS_TOKEN_URL="https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token"
-unset CYCLOPS_ACCESS_TOKEN
-```
-
-`CYCLOPS_ACCESS_TOKEN` (a short-lived access token) takes precedence over the
-client credentials and cannot renew itself.
-
-## Sizing
-
-Configure exactly one sizing mode per pool: `replicas` for a static warm size,
-or an `autoscaling` block (`min_pool_size`, `initial_pool_size`,
-`max_pool_size`) for claim-driven scaling. In autoscaling mode, `replicas`
-reports the current target after refresh. See
-[Keep sandboxes warm](/fleets/guides/warm-pools).
-
-## A Linux pool
-
-This KubeVirt pool runs the canonical desktop disk and publishes cua-spacesd as
-the `env` service, which the SDK and CLI use for shell, files and screen:
-
-```hcl title="main.tf" test="terraform" id="main-tf"
-terraform {
- required_providers {
- fleets = {
- source = "trycua/fleets"
- version = "0.2.0"
- }
- }
-}
-
-provider "fleets" {
- endpoint = "https://run.cua.ai"
-}
-
-resource "fleets_pool" "linux" {
- name = "linux-pool"
- cpu_cores = 4
- memory = "8Gi"
- container_disk_image = "ghcr.io/trycua/linux:24.04-disk"
- runtime = "kubevirt"
- firmware = "bios"
-
- service {
- name = "env"
- target_port = 3211
- protocol = "TCP"
- }
-
- autoscaling {
- min_pool_size = 0
- initial_pool_size = 1
- max_pool_size = 5
- }
-}
-
-output "linux_pool" {
- value = {
- name = fleets_pool.linux.name
- namespace = fleets_pool.linux.namespace
- target_replicas = fleets_pool.linux.replicas
- current_replicas = fleets_pool.linux.current_replicas
- ready_replicas = fleets_pool.linux.ready_replicas
- }
-}
-```
-For a Windows pool, use a distinct `name`, `firmware = "efi"`, and a
-`readiness_probe_json` that waits for the port your image serves (for example
-`tcpSocket = { port = 3211 }` with a long `failureThreshold`).
-
-## Apply and destroy
-
-```bash skip="third-party-cli"
-terraform init
-terraform plan
-terraform apply
-terraform output
-terraform destroy # deletes the pool and its namespace
-```
-
-Commit `.terraform.lock.hcl`. The provider reports the pool's `namespace`, its
-`replicas` target and the `current_replicas` and `ready_replicas` counts.
-
-## Export an existing pool
-
-`cua fleet pool export NAME --terraform` (Python:
-`Pool.export(name, terraform=True)`) prints a pool made with `Sandbox.create`
-or `Pool.apply` as a `fleets_pool` block: `command`, `args`, `env`,
-`process_mode`, `claim_secrets`, TTLs, services, autoscaling and one `sidecar`
-block per sidecar. A private-registry pool also gets a `fleets_registry_secret`
-resource whose username and password are Terraform variables.
-
-```hcl skip="pseudo"
- sidecar {
- name = "db"
- image = "redis:7-alpine"
- ports = [6379]
- cpu = "250m"
- memory = "256Mi"
- }
-```
-
-The process fields, TTLs and `sidecar` blocks need a `trycua/fleets` provider
-newer than 0.3.0.
-
-## Troubleshoot
-
-- `name` is a lowercase DNS label of at most 63 characters. Changing it
- replaces the pool and its namespace.
-- `403` on create: check the image reference and pull policy
- (`image_pull_secret` defaults to `ecr-credentials`).
-- Firmware must match the disk: `bios` or `efi` for amd64 Linux, `efi` for
- Windows.
-- Terraform state and shell history hold secrets; protect them.
diff --git a/docs/content/docs/fleets/guides/troubleshoot.mdx b/docs/content/docs/fleets/guides/troubleshoot.mdx
deleted file mode 100644
index fccb01bd41..0000000000
--- a/docs/content/docs/fleets/guides/troubleshoot.mdx
+++ /dev/null
@@ -1,57 +0,0 @@
----
-title: Troubleshoot cloud sandboxes
-description: Diagnose credential, access, image and readiness errors on Fleet, and clean up sandboxes and pools left behind.
----
-
-Start with what the current credentials can see, and keep tokens and signed
-URLs out of shared logs:
-
-```bash test="cli-shape" id="cua-sb-ls"
-cua auth whoami
-cua sb ls --cloud
-cua fleet pools ls
-```
-
-## Errors
-
-| Error | Cause and fix |
-| --- | --- |
-| `Fleet credentials missing` | No API key and no `cua auth login` session. Sign in, export a key, or run with `local=True` |
-| `401` | Revoked key, expired token, or `CUA_FLEET_BASE_URL` / `CUA_TOKEN_URL` pointing elsewhere. A stale `FLEETS_TOKEN` wins over a key; unset it |
-| `403` Payment method required | Add one in the dashboard |
-| `403` on create pool (`PoolAccessDeniedError`) | Pool names are global; another account owns it |
-| `403` on template | The image or its pull policy is not allowed: make it public or pass a [registry secret](/cua-sdk/guides/images#private-registries) |
-| `InvalidArgument` before anything is created | The runtime cannot run the image (`gvisor` needs a container image, `kubevirt` a containerDisk, both amd64), the sandbox has image layers the cloud cannot build yet, or a service uses a reserved name (`main`, `sidecars`, `sc`) next to sidecars |
-| `SpacesdNotAvailable` | The image has no cua-spacesd on `3211`; use its own services or an image that ships it |
-
-A `403` never proves a resource is absent.
-
-## A sandbox does not become ready
-
-`progress=print` in Python (the CLI prints the same stages) shows where it
-waits. In `provisioning`, capacity is being found: a cold image takes a few
-minutes, and an image the cloud cannot pull stays there. In `starting`, your
-`wait_for` probes run: check that the server listens on the declared port on a
-non-loopback address. `cua sb logs NAME --source guest` shows the guest log.
-Raise the wait budget (`time_to_start=`, `--ready-timeout`) only after that; it
-does not extend any TTL.
-
-## Clean up leftovers
-
-A run that stopped early needs no rerun: a cloud sandbox expires after its TTL
-(15 minutes by default) and idle managed pools are deleted after 30 minutes.
-To clean up now:
-
-```bash test="cli-shape" id="cua-fleet-pools-gc"
-cua sb rm -f first-fleet # a named CLI sandbox
-cua fleet pools gc --idle 5m # idle managed pools and stuck claims
-```
-
-- A named Python sandbox: `await (await Sandbox.connect(NAME)).close()`.
-- A pool you own: `await pool.delete()` from `Pool.apply`, or
- `fleet.deletePool(NAME)` in TypeScript, after its users release their claims.
- `gc` never touches pools you created.
-
-Deletion is asynchronous; list again until the resource is gone. Add a
-[TTL](/fleets/guides/capacity-and-claims#expiry) to disposable work as a
-backstop.
diff --git a/docs/content/docs/fleets/guides/warm-pools.mdx b/docs/content/docs/fleets/guides/warm-pools.mdx
deleted file mode 100644
index e82c9826ed..0000000000
--- a/docs/content/docs/fleets/guides/warm-pools.mdx
+++ /dev/null
@@ -1,60 +0,0 @@
----
-title: Keep sandboxes warm
-description: Keep ready sandboxes in a managed or dedicated pool so claims bind in seconds, and size warm capacity against cost.
----
-
-A warm replica is a booted sandbox waiting for a claim. A claim on a warm pool
-binds in seconds; a claim on a cold pool waits for the image to pull and boot,
-which can take a few minutes. Warm replicas consume capacity, and are billed,
-whether or not anything claims them.
-
-## Managed pools
-
-`Sandbox.create(image, local=False)` claims from a managed pool that scales
-from zero. `CloudOptions(warm=True)` keeps one sandbox of that image and shape
-ready. The canonical images (`Image.linux()`, `Image.windows()`) are warm by
-default; `CUA_FLEET_WARM` changes the default.
-
-```python test="docs" id="managed-warm" session="managed" prelude="fakefleet,image"
-from cua_sandbox import CloudOptions
-
-sb = await Sandbox.create(image, cloud=CloudOptions(warm=True, max_pool_size=20))
-```
-
-In the CLI, pass `--warm` or `--no-warm` to `cua sb create --on cloud`. A
-managed pool is deleted after 30 minutes without claims, warm or not.
-
-## Your own pools
-
-A pool you apply keeps capacity in one of two modes:
-
-| Mode | `PoolOptions` | Behavior |
-| --- | --- | --- |
-| Static | `replicas=N` (default 1) | Keeps N sandboxes, claimed or not |
-| Autoscaling | `min_pool_size`, `max_pool_size` (`warm=True` means a floor of 1) | Scales with claims between the bounds |
-
-```python test="docs,fleet" id="autoscaling-pool" session="pool" prelude="fakefleet,pool-name"
-import os
-from datetime import timedelta
-
-from cua_sandbox import Image, Pool, PoolOptions, SandboxSpec
-
-pool = await Pool.apply(
- os.environ["CUA_POOL_NAME"],
- SandboxSpec(image=Image.linux(), services={"env": 3211}),
- PoolOptions(min_pool_size=2, max_pool_size=10, idle_ttl=timedelta(hours=8)),
-)
-await pool.delete()
-```
-
-`idle_ttl` deletes the pool after that long without claims, so a forgotten
-warm pool does not run forever. In Terraform the same choice is `replicas` or
-an `autoscaling` block ([Terraform](/fleets/guides/terraform#sizing)).
-
-## Size it
-
-Set the floor to the claims you expect within one cold-start time, not to
-your peak: claims beyond the warm replicas still succeed after a cold start.
-A pool that must answer within a deadline (an external webhook) needs a warm
-replica for every concurrent claim. Terraform outputs and
-[run.cua.ai](https://run.cua.ai) show `ready_replicas`.
diff --git a/docs/content/docs/fleets/index.mdx b/docs/content/docs/fleets/index.mdx
deleted file mode 100644
index b5287e2cf0..0000000000
--- a/docs/content/docs/fleets/index.mdx
+++ /dev/null
@@ -1,52 +0,0 @@
----
-title: Cua Fleets
-description: Dedicated cloud capacity for sandboxes. Named pools, templates, claims, warm replicas and Terraform.
-landing:
- summary: 'Dedicated cloud capacity: pools, templates, claims, warm replicas and Terraform.'
- cta: Explore Cua Fleets
----
-
-Cua Fleets is the cloud behind `local=False`. A **pool** holds capacity for
-one sandbox template (image, runtime, size, command, services, sidecars). A
-**claim** reserves one sandbox from a pool. Named **services** route
-authenticated clients to ports inside the claimed sandbox.
-
-```text output
-pool (template: image, runtime, cpu/memory, command, services, sidecars; sizing)
- └─ claim ── bound sandbox ── services: env -> 3211, mcp -> 8765, ...
- │
- https://run.cua.ai/api/svc/{namespace}/{sandbox}-{service}
-```
-
-## Fleets or `local=False`
-
-`Sandbox.create(image, local=False)` already runs on Fleets: the SDK creates a
-managed pool per image and shape, scales it from zero and deletes it when
-idle. Use Fleets directly when you need what a managed pool does not give you.
-
-| | Managed pool (`local=False`) | Your own pool |
-| --- | --- | --- |
-| Created by | `Sandbox.create(image, local=False)`, `cua sb create IMAGE --on cloud` | `Pool.apply(...)`, Terraform |
-| Name | `cua-auto-<hash>`, per account, image and shape | You choose it, globally unique |
-| Sizing | Autoscales from zero to `max_pool_size` (10); canonical images keep one warm | `replicas`, or autoscaling bounds |
-| Shared by | One account's processes | Any process or team with access |
-| Cleanup | Deleted after 30 minutes idle | You delete it, or set a TTL |
-| Extras | | Terraform, [claim secrets](/fleets/guides/claim-secrets), creation-age TTLs, template updates |
-
-## Claims and services
-
-A claim's name is the sandbox's name (`cloud:<name>`). Releasing it returns or
-deletes the sandbox; the pool stays. Its TTL (15 minutes by default) is renewed
-while a process holds it. The `env` service (port `3211`) is cua-spacesd, when
-the image has it. Pools run containers under gVisor and VMs under KubeVirt,
-amd64 only ([images](/fleets/guides/images)).
-
-## Guides
-
-- [Create capacity and claim from it](/fleets/guides/capacity-and-claims)
-- [Keep sandboxes warm](/fleets/guides/warm-pools)
-- [Manage pools with Terraform](/fleets/guides/terraform)
-- [Publish a Fleet image](/fleets/guides/images)
-- [Add sidecars on Fleet](/fleets/guides/sidecars)
-- [Deliver per-claim secrets](/fleets/guides/claim-secrets)
-- [Troubleshoot](/fleets/guides/troubleshoot)
diff --git a/docs/content/docs/fleets/meta.json b/docs/content/docs/fleets/meta.json
deleted file mode 100644
index 72fe2b4f80..0000000000
--- a/docs/content/docs/fleets/meta.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
- "title": "Cua Fleets",
- "root": true,
- "pages": [
- "index",
- "quickstart",
- "guides",
- "reference"
- ]
-}
diff --git a/docs/content/docs/fleets/quickstart.mdx b/docs/content/docs/fleets/quickstart.mdx
deleted file mode 100644
index a60e0fa2ab..0000000000
--- a/docs/content/docs/fleets/quickstart.mdx
+++ /dev/null
@@ -1,114 +0,0 @@
----
-title: Quickstart
-description: Your first cloud sandbox and your first pool. Start a desktop in the cloud, verify a file hash, then apply a pool and claim from it.
----
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-Start a Linux desktop in the cloud, hash a file inside it and check the hash
-on your machine, then create a pool of your own and claim a sandbox from it.
-
-## Prerequisites
-
-- The `cua` CLI, signed in (`cua auth login --remote` without a browser):
-
-```bash test="cli-shape" id="cua-auth-login"
-curl -fsSL https://cua.ai/install.sh | sh
-cua auth login
-```
-
-- For scripts: Python `>=3.11,<3.14` with [`uv`](https://docs.astral.sh/uv/),
- or Node.js 20. They read `CUA_CLIENT_ID` and `CUA_CLIENT_SECRET` from
- `cua auth keys create NAME` ([credentials](/cua-sdk/guides/cloud#credentials)).
-
-Usage is billed while a sandbox runs; releasing it ends the charge.
-
-## Run a cloud sandbox
-
-<Tabs groupId="language" persist items={['CLI', 'Python', 'TypeScript']}>
- <Tab value="CLI">
-
-```bash test="cli-shape" id="cua-sb-create"
-cua sb create linux --on cloud --name first-fleet
-printf 'pear\napple\npear\nbanana\n' > fruit.txt
-cua sb cp fruit.txt first-fleet:/tmp/fruit.txt
-cua sb exec first-fleet sha256sum /tmp/fruit.txt
-shasum -a 256 fruit.txt
-cua sb screenshot first-fleet -o first-fleet.png
-```
-
- </Tab>
- <Tab value="Python">
-
-The script pins `cua-sandbox==0.9.0` and runs `Image.linux()` with
-`local=False` (`CUA_FLEET_IMAGE` overrides the image).
-
-```bash skip="third-party-cli"
-curl -fsSLO https://cua.ai/docs-assets/scripts/first-cloud-fleet/first_cloud_fleet.py
-uv run first_cloud_fleet.py
-```
-
- </Tab>
- <Tab value="TypeScript">
-
-```bash skip="host-install"
-npm install @trycua/[email protected] && npm install --save-dev tsx
-curl -fsSLo first-cloud-fleet.ts \
- https://cua.ai/docs-assets/scripts/first-cloud-fleet/first-cloud-fleet.ts.txt
-npx tsx first-cloud-fleet.ts
-```
-
- </Tab>
-</Tabs>
-
-Both hashes are
-`d9359aad71bda9a11a4fd2e8d72044d6f0f77519c6b6fb30d251806febcfb4d0`. Your
-machine computed the second one, so the check does not rely on the guest. The
-canonical image keeps warm capacity, so this takes seconds; another image's
-first start can take a few minutes.
-
-## Create a pool and claim from it
-
-The sandbox above ran on a pool the SDK manages. Apply a pool you own, with
-one warm replica, claim a sandbox from it, and delete it:
-
-```python test="docs,fleet" id="first-pool" prelude="fakefleet,pool-name"
-import os
-
-from cua_sandbox import CloudOptions, Image, Pool, PoolOptions, Sandbox, SandboxSpec
-
-pool = await Pool.apply(
- os.environ["CUA_POOL_NAME"], # globally unique, lowercase
- SandboxSpec(image=Image.linux(), services={"env": 3211}),
- PoolOptions(replicas=1),
-)
-async with Sandbox.ephemeral(cloud=CloudOptions(pool=pool.name)) as sb:
- print((await sb.shell.run("uname -a")).stdout.strip())
-await pool.delete()
-```
-
-## Result
-
-```text output
-Claimed ...
-Verified SHA-256: d9359aad71bda9a11a4fd2e8d72044d6f0f77519c6b6fb30d251806febcfb4d0
-Screenshot: .../first-cloud-fleet.png
-Claim released
-```
-
-## Clean up
-
-```bash test="cli-shape" id="cua-sb-rm-first-fleet"
-cua sb rm -f first-fleet
-```
-
-The scripts release their sandbox even when a step fails. A killed process's
-sandbox expires after its TTL (15 minutes); idle managed pools are deleted
-after 30 minutes, or now with `cua fleet pools gc`
-([Troubleshoot](/fleets/guides/troubleshoot#clean-up-leftovers)).
-
-## Next
-
-- [Create capacity and claim from it](/fleets/guides/capacity-and-claims)
-- [Manage pools with Terraform](/fleets/guides/terraform)
-- [Keep sandboxes warm](/fleets/guides/warm-pools)
diff --git a/docs/content/docs/fleets/reference/api-key.mdx b/docs/content/docs/fleets/reference/api-key.mdx
deleted file mode 100644
index d2078bc6a3..0000000000
--- a/docs/content/docs/fleets/reference/api-key.mdx
+++ /dev/null
@@ -1,64 +0,0 @@
----
-title: "API key"
-description: "OAuth client credentials that act for your user, for the SDK, CLI and Terraform."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: libs/fleet/backend/docs/swagger.json
- Version: 0.4.1
-*/}
-
-On this page: [REST](#rest)
-
-## REST
-
-### Create an API key
-
-```http
-POST /api/user-keys
-```
-
-Body (`application/json`):
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `name` | `string` | none | A name for the key. |
-| `scope` | `string[]` | none | Namespaces the key is limited to. |
-
-Returns: `201` with:
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `client_id` | `string` | none | OAuth client ID. |
-| `client_secret` | `string` | none | OAuth client secret. Returned once; it cannot be read again. |
-| `name` | `string` | none | The key's name. |
-| `scope` | `string[]` | none | Namespaces the key is limited to. |
-| `token_url` | `string` | none | Token endpoint for the client-credentials grant. |
-
-Errors: [`400`](/fleets/reference/errors#http-400), [`401`](/fleets/reference/errors#http-401) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### List API keys
-
-```http
-GET /api/user-keys
-```
-
-Returns: `200` with an object with `keys` (object[]), `keys[].client_id` (string), `keys[].id` (string), `keys[].name` (string), `keys[].scope` (string[]).
-
-Errors: [`401`](/fleets/reference/errors#http-401) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Revoke an API key
-
-```http
-DELETE /api/user-keys/{id}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `id` | path | The object id. |
-
-Returns: `204`. No Content.
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403) ([Errors](/fleets/reference/errors#http-status-codes)).
diff --git a/docs/content/docs/fleets/reference/claim.mdx b/docs/content/docs/fleets/reference/claim.mdx
deleted file mode 100644
index a93a1035b6..0000000000
--- a/docs/content/docs/fleets/reference/claim.mdx
+++ /dev/null
@@ -1,178 +0,0 @@
----
-title: "Claim"
-description: "A lease on one sandbox from a pool, until it is released or expires."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: cua-fleet fleet-docs-dump (osgym.cua.ai CRDs); libs/fleet/sdk/src (routes, methods); libs/fleet/backend/docs/swagger.json; cua-sdk src/native/fleet.rs
- Version: 0.4.1
-*/}
-
-On this page: [Object](#the-claim-object) · [REST](#rest) · [SDK](#sdk)
-
-## The claim object
-
-`apiVersion: osgym.cua.ai/v1alpha1`, `kind: OSGymSandboxClaim`, in the pool's namespace. Plural `osgymsandboxclaims`, short name `osbc`. `metadata` is standard Kubernetes object metadata (`name`, `namespace`, `labels`).
-
-### Spec
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `spec.bindDeadline` | `integer` | none | Seconds the claim may stay Pending before it is marked Failed (Fleet's default and the SDK's value: 900). A Pending claim is what grows an autoscaled pool, so leave room for a cold boot. At least 0. |
-| `spec.lifecycle` | `object` | none | When the claim expires and what happens to its sandbox. |
-| `spec.lifecycle.autoRenew` | `boolean` | `false` | Set by Fleet on claims it renews itself. Leave it `false`. |
-| `spec.lifecycle.shutdownPolicy` | `string` | `"Retain"` | `Retain`: when the claim is deleted, the sandbox returns to the pool and restarts clean. `Delete`: the sandbox is destroyed and the pool creates a new one. |
-| `spec.lifecycle.shutdownTime` | `string` | none | Absolute UTC expiry (RFC 3339). Fleet deletes the claim, and releases its sandbox, once it passes. Renew by patching it forward. |
-| `spec.sandboxTemplateRef` | `object` | required | The template of the pool to claim from. |
-| `spec.sandboxTemplateRef.name` | `string` | required | OSGymSandboxTemplate the warm pool's OSGymSandboxes use. |
-| `spec.secretRef` | `object` | none | Secret in the claim's namespace whose keys the pool-operator delivers as files into the bound sandbox once it binds, without restarting it: each key becomes /run/cua/&lt;key&gt; (mode 0600), e.g. env-token -&gt; /run/cua/env-token for cua-env-driver. The data is copied into an operator-owned per-sandbox Secret, never into the claim status, and is wiped when the claim is released. The name must be cua-claim-&lt;claim name&gt;, and the claim's template must set vmTemplate.claimSecrets, or the claim fails. |
-| `spec.secretRef.name` | `string` | required | Secret name (must start with cua-claim-). At most 253 characters. Matches `^cua-claim-[a-z0-9]([-a-z0-9]*[a-z0-9])?$`. |
-| `spec.ttlSecondsAfterCreated` | `integer` | none | Creation-age TTL in seconds. When absent, the resource is not automatically reaped based on age. At least 0. |
-| `spec.warmpool` | `string` | `"default"` | Where to take a sandbox from: `default` (the pool running the template), `none`, or a pool name. |
-
-### Status
-
-Set by Fleet; read-only.
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `status.conditions` | `object[]` | none | Kubernetes conditions of the claim. |
-| `status.conditions[].lastTransitionTime` | `string` | none | When the condition last changed (RFC 3339). |
-| `status.conditions[].message` | `string` | none | Human-readable detail. |
-| `status.conditions[].reason` | `string` | none | Machine-readable reason. |
-| `status.conditions[].status` | `string` | none | `True`, `False` or `Unknown`. |
-| `status.conditions[].type` | `string` | none | Condition type. |
-| `status.phase` | `string` | none | `Pending`, `Bound` or `Failed`. |
-| `status.sandbox` | `object` | none | The bound sandbox. |
-| `status.sandbox.name` | `string` | none | Name of the bound sandbox. |
-| `status.sandbox.service` | `string` | none | In-cluster DNS name of the sandbox's Service. |
-
-### Fields the SDK adds
-
-Written as JSON beyond the published schema; Fleet reads them.
-
-| Field | Type | Description |
-| --- | --- | --- |
-| `spec.secretRef.name` | `string` | The claim's `cua-claim-<claim>` Secret. The template must set `claimSecrets`. |
-
-### Example
-
-What the SDK sends for a default pool of the cua Linux image (`PoolSpec::new`, built by `cua-fleet`).
-
-```json
-{
- "apiVersion": "osgym.cua.ai/v1alpha1",
- "kind": "OSGymSandboxClaim",
- "metadata": {
- "name": "claim-1",
- "namespace": "my-pool"
- },
- "spec": {
- "bindDeadline": 900,
- "sandboxTemplateRef": {
- "name": "my-pool"
- }
- }
-}
-```
-
-## REST
-
-### Create claim
-
-```http
-POST /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxclaims
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-
-Body: the [claim object](#the-claim-object) (`application/json`).
-
-Returns: `200`, `201`, `202` with the [claim object](#the-claim-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### List claims
-
-```http
-GET /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxclaims
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-
-Returns: `200` with `{"items": [...]}`, a list of the [claim object](#the-claim-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Get claim
-
-```http
-GET /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxclaims/{name}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Returns: `200` with the [claim object](#the-claim-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Renew claim
-
-```http
-PATCH /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxclaims/{name}
-```
-
-Push the claim's `spec.lifecycle.shutdownTime` forward. That absolute expiry is the only liveness input the pool operator's claim reaper honors, so a holder that outlives its current lease must renew before the deadline passes or the bound sandbox is deleted underneath it. Deliberately narrower than a claim update: nothing else on the claim can be mutated through the SDK.
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Body: a JSON merge patch of the [claim object](#the-claim-object) (`application/merge-patch+json`).
-
-Returns: `200` with the [claim object](#the-claim-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Delete claim
-
-```http
-DELETE /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxclaims/{name}
-```
-
-Delete the claim and, when it references a claim-scoped Secret (`secret_files`), that Secret too. The pool-operator also owner-refs the Secret to the claim, so garbage collection is the backstop.
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Returns: `200`, `202`, `204` with no body.
-
-`404` is treated as success: the object is already gone.
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-## SDK
-
-Methods of the `Fleet` handle (`cua.fleet()`), with signatures in every language in the [Cua SDK reference](/cua-sdk/reference).
-
-| Method | Returns | Description |
-| --- | --- | --- |
-| [`Fleet.acquire(pool, name, ttl_seconds)`](/cua-sdk/reference/fleet/claims#fleetacquire) | `FleetSandbox` | Claims a sandbox from a pool and waits for it to bind. |
-| [`Fleet.acquire_with(pool, options)`](/cua-sdk/reference/fleet/claims#fleetacquire_with) | `FleetSandbox` | `Fleet::acquire` with claim options, including a per-claim env token (bounded wait for its delivery; `ClaimSecretsNotDelivered` releases the claim). |
-| [`Fleet.claim(pool, name, ttl_seconds)`](/cua-sdk/reference/fleet/claims#fleetclaim) | `FleetClaim` | Creates a claim without waiting. |
-| [`Fleet.attach_claim(namespace, name)`](/cua-sdk/reference/fleet/claims#fleetattach_claim) | `FleetSandbox` | Waits for a named claim to bind. |
-| [`Fleet.list_claims(namespace)`](/cua-sdk/reference/fleet/claims#fleetlist_claims) | `FleetClaim[]` | Lists claims in a namespace. |
-| [`Fleet.keep_alive(namespace, name, seconds)`](/cua-sdk/reference/fleet/claims#fleetkeep_alive) | `string` | Extends a claim's lease; returns the RFC 3339 shutdown time. |
-| [`Fleet.release(namespace, name)`](/cua-sdk/reference/fleet/claims#fleetrelease) | none | Releases a claim (missing claims are fine). |
diff --git a/docs/content/docs/fleets/reference/errors.mdx b/docs/content/docs/fleets/reference/errors.mdx
deleted file mode 100644
index e022856dc4..0000000000
--- a/docs/content/docs/fleets/reference/errors.mdx
+++ /dev/null
@@ -1,256 +0,0 @@
----
-title: "Errors"
-description: "Fleet HTTP status codes and SDK errors, with causes and fixes."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: swagger.json responses; cua-fleet src/lib.rs Error; libs/fleet/sdk/src/error.rs SdkError; cua-daemon mapping
- Version: 0.4.1
-*/}
-
-Every error the Fleet API and the Fleet SDK layer return, with its cause and fix. SDK languages surface them as [`CuaError`](/cua-sdk/reference/errors) cases, named in each entry.
-
-## HTTP status codes
-
-Errors from the gateway carry `{"error": "<message>"}`; errors from the Kubernetes proxy carry a Kubernetes `Status` object with `message` and `reason`.
-
-| Status | Meaning |
-| --- | --- |
-| [`400`](#http-400) | The request is malformed: a missing field, a bad name, or a value out of range. |
-| [`401`](#http-401) | No token, or an expired or invalid one. |
-| [`403`](#http-403) | The token is valid but may not act on this namespace, or the proxy does not allow this request. On a read, Fleet answers 403 for a namespace that no longer exists; on a pool write, the pool name belongs to another account. |
-| [`404`](#http-404) | The object does not exist. |
-| [`409`](#http-409) | An object with that name exists. |
-| [`500`](#http-500) | Fleet failed to process the request. |
-| [`502`](#http-502) | Fleet could not reach the backend behind the gateway (the Kubernetes API or the sandbox service). |
-| [`503`](#http-503) | The feature is not configured in this environment (for example signed service URLs). |
-
-### HTTP 400
-
-The request is malformed: a missing field, a bad name, or a value out of range.
-
-Fix: Check the body against the object reference; the `error` message names the field.
-
-### HTTP 401
-
-No token, or an expired or invalid one.
-
-Fix: Send `Authorization: Bearer <token>` with a fresh token from your API key.
-
-### HTTP 403
-
-The token is valid but may not act on this namespace, or the proxy does not allow this request. On a read, Fleet answers 403 for a namespace that no longer exists; on a pool write, the pool name belongs to another account.
-
-Fix: Check the namespace and name. For a new pool, pick another pool name (names are unique across accounts).
-
-### HTTP 404
-
-The object does not exist.
-
-Fix: Check the name and namespace; list the collection to see what exists.
-
-### HTTP 409
-
-An object with that name exists.
-
-Fix: Use another name, or read the existing object.
-
-### HTTP 500
-
-Fleet failed to process the request.
-
-Fix: Retry; report persistent failures with the request and time.
-
-### HTTP 502
-
-Fleet could not reach the backend behind the gateway (the Kubernetes API or the sandbox service).
-
-Fix: Retry. For a service URL, check that the sandbox is bound and its service is listening.
-
-### HTTP 503
-
-The feature is not configured in this environment (for example signed service URLs).
-
-Fix: Use the SDK service URL instead, or contact support.
-
-## SDK errors
-
-Raised by the Fleet layer of the SDK (`cua_fleet::Error`).
-
-| Error | Surfaces as |
-| --- | --- |
-| [`MissingCredentials`](#missingcredentials) | `CuaError.ProviderNotConfigured` |
-| [`InvalidArgument`](#invalidargument) | `CuaError.InvalidArgument` |
-| [`Sdk`](#sdk) | `CuaError.NotFound` (a missing object), else `CuaError.Fleet` |
-| [`AdmissionDenied`](#admissiondenied) | `CuaError.FleetAdmissionDenied` |
-| [`CreditExhausted`](#creditexhausted) | `CuaError.CloudCreditExhausted` |
-| [`UnknownService`](#unknownservice) | `CuaError.NotFound` |
-| [`Timeout`](#timeout) | `CuaError.Timeout` |
-| [`Env`](#env) | `CuaError.SpacesdNotAvailable`, `CuaError.Unauthenticated`, `CuaError.InvalidArgument`, `CuaError.Timeout`, `CuaError.Transport`, `CuaError.Env` |
-| [`Unsupported`](#unsupported) | `CuaError.Unsupported` |
-| [`PoolSpecMismatch`](#poolspecmismatch) | `CuaError.PoolSpecMismatch` |
-| [`ClaimSecretsNotDelivered`](#claimsecretsnotdelivered) | `CuaError.ClaimSecretsNotDelivered` |
-
-### MissingCredentials
-
-No Fleet credentials: neither a `cua auth login` session, `FLEETS_TOKEN` nor `CUA_CLIENT_ID` + `CUA_CLIENT_SECRET` (`MISSING_CREDENTIALS`). Run `cua auth login`, set the client credentials, or run the sandbox locally.
-
-```text
-Fleet credentials missing: run `cua auth login` or set CUA_CLIENT_ID/CUA_CLIENT_SECRET, or pass local=True
-```
-
-Surfaces as `CuaError.ProviderNotConfigured`.
-
-### InvalidArgument
-
-A value the SDK checks before calling Fleet is invalid (a name that is not a DNS label, a bad secret, an unusable spec). The message names the value; fix it and retry.
-
-```text
-invalid argument: <0>
-```
-
-Surfaces as `CuaError.InvalidArgument`.
-
-### Sdk
-
-The Fleet API call failed: an HTTP status, a transport or token failure, or an unexpected body (`SdkError`, listed under Fleet API client errors).
-
-Surfaces as `CuaError.NotFound` (a missing object), else `CuaError.Fleet`.
-
-### AdmissionDenied
-
-Fleet's admission refused a write: a sandbox size or pool size over this account's limits, or a template its policy does not admit. The message is Fleet's own and names the limit. Change the value, or ask Cua support to raise the account's limits.
-
-```text
-Fleet refused <operation> (HTTP <status>): <message>
-```
-
-Surfaces as `CuaError.FleetAdmissionDenied`.
-
-### CreditExhausted
-
-The account is out of Cua Cloud credit: no credit left, and no card or plan (Fleet answers HTTP 402 `cloud_credit_exhausted`). Running sandboxes keep running; new ones are refused. Add credit (a plan or a card for pay as you go) on the page at `billing_url`.
-
-```text
-<message> Add credit at <billing_url>
-```
-
-Surfaces as `CuaError.CloudCreditExhausted`.
-
-### UnknownService
-
-The claim's sandbox does not expose the service. Use one of the services its template declares (`available`), or add the service to the pool's template.
-
-```text
-sandbox <sandbox> exposes no service <service> (available: <available>)
-```
-
-Surfaces as `CuaError.NotFound`.
-
-### Timeout
-
-A wait ran out: a pool that never became ready, or a claim that never bound. Check the pool's ready replicas and capacity, then retry with a longer timeout.
-
-```text
-timed out: <0>
-```
-
-Surfaces as `CuaError.Timeout`.
-
-### Env
-
-The claimed sandbox's cua-spacesd failed or is unreachable.
-
-Surfaces as `CuaError.SpacesdNotAvailable`, `CuaError.Unauthenticated`, `CuaError.InvalidArgument`, `CuaError.Timeout`, `CuaError.Transport`, `CuaError.Env`.
-
-### Unsupported
-
-The runtime or this Fleet release cannot run what the spec asks (for example `env` on a KubeVirt pool). The message names the field; drop it or pick a runtime that supports it.
-
-```text
-unsupported: <0>
-```
-
-Surfaces as `CuaError.Unsupported`.
-
-### PoolSpecMismatch
-
-Surfaces as `CuaError.PoolSpecMismatch`.
-
-### ClaimSecretsNotDelivered
-
-Surfaces as `CuaError.ClaimSecretsNotDelivered`.
-
-## Fleet API client errors
-
-The Fleet API client under the SDK (`SdkError`). They reach SDK callers through `Sdk` above: as `CuaError.NotFound` for a missing object, otherwise `CuaError.Fleet`, with this message.
-
-### Configuration
-
-```text
-invalid configuration: <reason>
-```
-
-### InvalidResourceName
-
-```text
-invalid <field> <value>: <reason>
-```
-
-### Transport
-
-```text
-transport error: <reason>
-```
-
-### Token
-
-```text
-token error: <reason>
-```
-
-### Body
-
-```text
-invalid response body: <reason>
-```
-
-### Status
-
-```text
-<operation> returned HTTP <status>: <body>
-```
-
-### SignedServiceUrlsUnavailable
-
-```text
-signed service URLs are not configured in this environment
-```
-
-### SdkError.UnknownService
-
-```text
-unknown sandbox service <requested>; available services: <available>
-```
-
-### InvalidServicePath
-
-```text
-invalid service path: <path>
-```
-
-### ClaimFailed
-
-```text
-claim entered terminal phase <phase>: <status>
-```
-
-### ClaimTimeout
-
-```text
-claim did not bind before the polling limit
-```
-
-### PoolAccessDenied
diff --git a/docs/content/docs/fleets/reference/image.mdx b/docs/content/docs/fleets/reference/image.mdx
deleted file mode 100644
index bd02055be8..0000000000
--- a/docs/content/docs/fleets/reference/image.mdx
+++ /dev/null
@@ -1,176 +0,0 @@
----
-title: "Image"
-description: "A build recipe Fleet turns into a runnable image, and its build status."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: cua-image schema/image-v1alpha1.schema.json; libs/fleet/sdk/src (routes, methods); libs/fleet/backend/docs/swagger.json; cua-sdk src/native/fleet.rs
- Version: 0.4.1
-*/}
-
-On this page: [Object](#the-image-object) · [REST](#rest) · [SDK](#sdk)
-
-## The image object
-
-The full Image resource. `apiVersion: images.cua.ai/v1alpha1`, `kind: Image`. The same resource `cua image build` reads from `image.json`.
-
-Fleet does not build `kind: container` recipes yet: a cloud Image with layers fails with a clear error. Build it locally and push it to a registry instead.
-
-### Metadata and spec
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `metadata.annotations` | `map of string` | none | Annotations on the Image resource. |
-| `metadata.labels` | `map of string` | none | Labels on the Image resource. |
-| `metadata.name` | `string` | required | Image name: a DNS label. 1 to 63 characters. Matches `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`. |
-| `metadata.namespace` | `string` | required | Namespace the image belongs to. 1 to 63 characters. Matches `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`. |
-| `spec.build` | `object` | none | Build resources and limits. |
-| `spec.build.diskSize` | `string` | `"40Gi"` | Disk size of the build machine (default `40Gi`). Matches `^[1-9][0-9]*(Gi\|Ti)$`. |
-| `spec.build.timeoutSeconds` | `integer` | `7200` | Build budget in seconds (default 7200). 60 to 86400. |
-| `spec.metadata` | `object` | none | Free-form metadata kept with the image. |
-| `spec.metadata.tags` | `map of string` | none | Tags, as key-value pairs. |
-| `spec.recipe` | `object` | required | What to build. |
-| `spec.recipe.distro` | `string` | required | Distribution of the base, for example `ubuntu`. 1 to 64 characters. |
-| `spec.recipe.env` | `map of string` | none | Environment variables of the image. |
-| `spec.recipe.files` | `object[]` | none | Uploaded files copied into the image. At most 128 items. |
-| `spec.recipe.files[].destination` | `string` | required | Absolute path in the image. At most 4096 characters. Matches `^/.*`. |
-| `spec.recipe.files[].source` | `object` | required | The uploaded file. |
-| `spec.recipe.files[].source.digest` | `string` | required | SHA-256 digest of the file. Matches `^sha256:[0-9a-f]{64}$`. |
-| `spec.recipe.files[].source.reference` | `string` | required | Upload reference from the image upload API (`uploads/<namespace>/<id>`). 1 to 2048 characters. Matches `^uploads/[a-z0-9]([-a-z0-9]*[a-z0-9])?/[A-Za-z0-9_-]+$`. |
-| `spec.recipe.files[].source.sizeBytes` | `integer` | required | Size in bytes. At least 0. |
-| `spec.recipe.from` | `string` | none | Registry base image (`kind: container`): layers are built on top of it and the result is an OCI rootfs. 1 to 1024 characters. |
-| `spec.recipe.fromPullSecret` | `string` | none | A `cua-registry-*` pull Secret in this namespace for a private base. At most 253 characters. Matches `^cua-registry-[a-z0-9]([-a-z0-9]*[a-z0-9])?$`. |
-| `spec.recipe.kind` | `"vm" \| "container"` | required | `vm`: a VM disk image. `container`: an OCI rootfs built on `from`. |
-| `spec.recipe.layers` | `object[]` | required | Build steps, run in order. At most 128 items. |
-| `spec.recipe.osType` | `"linux"` | required | Guest OS family. |
-| `spec.recipe.ports` | `integer[]` | none | Ports the image exposes. At most 32 items. |
-| `spec.recipe.version` | `string` | required | Distribution version, for example `24.04`. 1 to 64 characters. |
-
-### Status
-
-Set by Fleet; read-only.
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `status.artifacts` | `object` | none | What the build produced. |
-| `status.artifacts.oci` | `object` | none | The built OCI image. |
-| `status.artifacts.oci.digest` | `string` | required | Image digest. Matches `^sha256:[0-9a-f]{64}$`. |
-| `status.artifacts.oci.reference` | `string` | required | Image reference. 1 to 2048 characters. |
-| `status.artifacts.volumeSnapshot` | `object` | none | The built VM disk, as a volume snapshot. |
-| `status.artifacts.volumeSnapshot.name` | `string` | required | Name of the snapshot. 1 to 253 characters. |
-| `status.artifacts.volumeSnapshot.namespace` | `string` | required | Namespace of the snapshot. 1 to 63 characters. |
-| `status.buildIdentity` | `string` | none | Identifier of the build run. At most 63 characters. |
-| `status.conditions` | `object[]` | none | Kubernetes-style conditions of the build. |
-| `status.conditions[].lastTransitionTime` | `string` | required | When the condition last changed (RFC 3339). |
-| `status.conditions[].message` | `string` | none | Human-readable detail. At most 32768 characters. |
-| `status.conditions[].observedGeneration` | `integer` | none | The spec generation the condition describes. At least 0. |
-| `status.conditions[].reason` | `string` | required | Machine-readable reason. 1 to 128 characters. |
-| `status.conditions[].status` | `"True" \| "False" \| "Unknown"` | required | `True`, `False` or `Unknown`. |
-| `status.conditions[].type` | `string` | required | Condition type. 1 to 64 characters. |
-| `status.logs` | `object` | none | Where the build log is. |
-| `status.logs.livePodName` | `string` | none | Pod that streams the log while the build runs. At most 253 characters. |
-| `status.logs.retainedReference` | `string` | none | Where the log is kept after the build. At most 2048 characters. |
-| `status.observedGeneration` | `integer` | none | The spec generation this status describes. At least 0. |
-| `status.phase` | `"Pending" \| "Validating" \| "Building" \| "PushingOCI" \| "Importing" \| "Quiescing" \| "Snapshotting" \| "Ready" \| "Failed" \| "Cancelling"` | none | Build phase. |
-| `status.recipeDigest` | `string` | none | Digest of the recipe that was built. Matches `^sha256:[0-9a-f]{64}$`. |
-
-### Layer types
-
-`spec.recipe.layers[]` holds build steps, each tagged by `type`.
-
-| `type` | Fields |
-| --- | --- |
-| `apt_install` | `packages` `string[]` |
-| `pip_install` | `packages` `string[]` |
-| `uv_install` | `packages` `string[]` |
-| `app_install` | `appId` `string` |
-| `run` | `command` `string` |
-
-## REST
-
-### Create image
-
-```http
-POST /api/k8s/apis/images.cua.ai/v1alpha1/namespaces/{namespace}/images
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-
-Body: the [image object](#the-image-object) (`application/json`).
-
-Returns: `201` with the [image object](#the-image-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### List images
-
-```http
-GET /api/k8s/apis/images.cua.ai/v1alpha1/namespaces/{namespace}/images
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-
-Returns: `200` with `{"items": [...]}`, a list of the [image object](#the-image-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Get image
-
-```http
-GET /api/k8s/apis/images.cua.ai/v1alpha1/namespaces/{namespace}/images/{name}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Returns: `200` with the [image object](#the-image-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Delete image
-
-```http
-DELETE /api/k8s/apis/images.cua.ai/v1alpha1/namespaces/{namespace}/images/{name}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Returns: `200`, `202`, `204` with no body.
-
-`404` is treated as success: the object is already gone.
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Presign image uploads
-
-```http
-POST /api/image-uploads/presign
-```
-
-Body (`application/json`): `namespace` (string), `files` (object[]). Each of `files[]` has `digest` (string), `sizeBytes` (integer), `name` (string): the file's SHA-256 digest, size and name.
-
-Returns: `200` with `files[]`, one instruction per file: `digest` (string), `sizeBytes` (integer), `reference` (string), `upload` (object). `reference` is what an image recipe's `files[].source.reference` names. `upload` (`method` (string), `url` (string), `headers` (map of string)) is a presigned request to send the bytes with; it is absent when Fleet already has the file.
-
-Errors: see [Errors](/fleets/reference/errors#http-status-codes).
-
-## SDK
-
-Methods of the `Fleet` handle (`cua.fleet()`), with signatures in every language in the [Cua SDK reference](/cua-sdk/reference).
-
-| Method | Returns | Description |
-| --- | --- | --- |
-| [`Fleet.create_image(namespace, manifest_json)`](/cua-sdk/reference/fleet/images#fleetcreate_image) | `string` | Creates an image resource (remote build) from a JSON manifest. |
-| [`Fleet.list_images(namespace)`](/cua-sdk/reference/fleet/images#fleetlist_images) | `string[]` | Lists image resources (JSON) in a namespace. |
-| [`Fleet.get_image(namespace, name)`](/cua-sdk/reference/fleet/images#fleetget_image) | `string` | Gets an image resource (JSON). |
-| [`Fleet.delete_image(namespace, name)`](/cua-sdk/reference/fleet/images#fleetdelete_image) | none | Deletes an image resource. |
diff --git a/docs/content/docs/fleets/reference/index.mdx b/docs/content/docs/fleets/reference/index.mdx
deleted file mode 100644
index 61b39a4f66..0000000000
--- a/docs/content/docs/fleets/reference/index.mdx
+++ /dev/null
@@ -1,57 +0,0 @@
----
-title: "Reference"
-description: "Cua Fleets objects, REST operations, SDK methods and Terraform schema."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: fleet-docs-dump; libs/fleet (client, swagger, Terraform provider); cua-sdk native/fleet.rs
- Version: 0.4.1
-*/}
-
-Everything Cua Fleets exposes, by object: the REST resources behind the Fleet API, the SDK `Fleet` handle, and the `trycua/fleets` Terraform provider.
-
-## Objects
-
-| Task | Object | Description |
-| --- | --- | --- |
-| Keep capacity | [Pool](/fleets/reference/pool) | Warm capacity: how many sandboxes of one template Fleet keeps ready to claim. |
-| Keep capacity | [Template](/fleets/reference/template) | What each sandbox of a pool runs: image, runtime, size, services and probes. |
-| Use a sandbox | [Claim](/fleets/reference/claim) | A lease on one sandbox from a pool, until it is released or expires. |
-| Use a sandbox | [Sandbox](/fleets/reference/sandbox) | One running machine of a pool, bound to at most one claim. |
-| Use a sandbox | [Secret](/fleets/reference/secret) | Secrets the SDK writes in a pool's namespace: a claim's env token and registry pull credentials. |
-| Use a sandbox | [Service URL](/fleets/reference/service-url) | HTTP and WebSocket access to a sandbox's services, and shareable signed URLs. |
-| Build images | [Image](/fleets/reference/image) | A build recipe Fleet turns into a runnable image, and its build status. |
-| Account | [Namespace](/fleets/reference/namespace) | The account-owned scope every pool, template, claim and secret lives in. |
-| Account | [API key](/fleets/reference/api-key) | OAuth client credentials that act for your user, for the SDK, CLI and Terraform. |
-| Configure | [Terraform provider](/fleets/reference/terraform) | Provider settings and the resources it manages. |
-| Debug | [Errors](/fleets/reference/errors) | HTTP statuses and SDK errors, with causes and fixes. |
-
-## Base URL and authentication
-
-- Base URL: `https://run.cua.ai` (`CUA_FLEET_BASE_URL` overrides it for the SDK).
-- Every request sends `Authorization: Bearer <token>`. Exchange an [API key](/fleets/reference/api-key) for a token with the OAuth client-credentials grant at `https://auth.cua.ai/realms/cyclops-cs/protocol/openid-connect/token`.
-- The SDK and CLI read `CUA_CLIENT_ID` and `CUA_CLIENT_SECRET`, a `cua auth login` session, or `FLEETS_TOKEN`.
-
-## Conventions
-
-- Pools, templates, claims and sandboxes are Kubernetes custom resources (`osgym.cua.ai/v1alpha1`) under `/api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/`. Images are `images.cua.ai/v1alpha1`.
-- A pool owns the namespace of the same name; its template and claims live there too.
-- Names are DNS labels: lowercase letters, digits and `-`, at most 63 characters.
-- Lists return `{"items": [...]}`. Updates are JSON merge patches (`Content-Type: application/merge-patch+json`).
-- Errors outside the Kubernetes proxy return `{"error": "<message>"}`.
-
-## Operations
-
-| Object | REST | SDK | Terraform |
-| --- | --- | --- | --- |
-| [Pool](/fleets/reference/pool) | [Create pool](/fleets/reference/pool#create-pool), [List pools](/fleets/reference/pool#list-pools), [Get pool](/fleets/reference/pool#get-pool), [Update pool](/fleets/reference/pool#update-pool), [Delete pool](/fleets/reference/pool#delete-pool) | `Fleet.apply_pool`, `Fleet.apply`, `Fleet.get_pool`, `Fleet.list_pools`, `Fleet.set_pool_replicas`, `Fleet.wait_pool_ready`, `Fleet.export_pool`, `Fleet.delete_pool`, `Fleet.ephemeral_pool_name`, `Fleet.pools` | `fleets_pool` |
-| [Template](/fleets/reference/template) | [Create template](/fleets/reference/template#create-template), [List templates](/fleets/reference/template#list-templates), [Get template](/fleets/reference/template#get-template), [Update template](/fleets/reference/template#update-template), [Delete template](/fleets/reference/template#delete-template) | `Fleet.apply_pool_template`, `Fleet.check_pool_spec`, `Fleet.list_templates` | `fleets_pool` |
-| [Claim](/fleets/reference/claim) | [Create claim](/fleets/reference/claim#create-claim), [List claims](/fleets/reference/claim#list-claims), [Get claim](/fleets/reference/claim#get-claim), [Renew claim](/fleets/reference/claim#renew-claim), [Delete claim](/fleets/reference/claim#delete-claim) | `Fleet.acquire`, `Fleet.acquire_with`, `Fleet.claim`, `Fleet.attach_claim`, `Fleet.list_claims`, `Fleet.keep_alive`, `Fleet.release` | none |
-| [Sandbox](/fleets/reference/sandbox) | none | `Fleet.attach_claim`, `Fleet.service_url` | none |
-| [Secret](/fleets/reference/secret) | none | none | none |
-| [Service URL](/fleets/reference/service-url) | [Call a service](/fleets/reference/service-url#call-a-service), [Create a signed URL](/fleets/reference/service-url#create-a-signed-url), [List signed URLs](/fleets/reference/service-url#list-signed-urls), [Revoke a signed URL](/fleets/reference/service-url#revoke-a-signed-url) | `Fleet.service_url`, `Fleet.create_signed_service_url` | none |
-| [Image](/fleets/reference/image) | [Create image](/fleets/reference/image#create-image), [List images](/fleets/reference/image#list-images), [Get image](/fleets/reference/image#get-image), [Delete image](/fleets/reference/image#delete-image), [Presign image uploads](/fleets/reference/image#presign-image-uploads) | `Fleet.create_image`, `Fleet.list_images`, `Fleet.get_image`, `Fleet.delete_image` | none |
-| [Namespace](/fleets/reference/namespace) | [Create a namespace](/fleets/reference/namespace#create-a-namespace), [List namespaces](/fleets/reference/namespace#list-namespaces), [Get a namespace](/fleets/reference/namespace#get-a-namespace), [Delete a namespace](/fleets/reference/namespace#delete-a-namespace) | none | none |
-| [API key](/fleets/reference/api-key) | [Create an API key](/fleets/reference/api-key#create-an-api-key), [List API keys](/fleets/reference/api-key#list-api-keys), [Revoke an API key](/fleets/reference/api-key#revoke-an-api-key) | none | none |
diff --git a/docs/content/docs/fleets/reference/meta.json b/docs/content/docs/fleets/reference/meta.json
deleted file mode 100644
index b6a8c5a40a..0000000000
--- a/docs/content/docs/fleets/reference/meta.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
- "title": "Reference",
- "pages": [
- "index",
- "pool",
- "template",
- "claim",
- "sandbox",
- "secret",
- "service-url",
- "image",
- "namespace",
- "api-key",
- "terraform",
- "errors"
- ]
-}
diff --git a/docs/content/docs/fleets/reference/namespace.mdx b/docs/content/docs/fleets/reference/namespace.mdx
deleted file mode 100644
index 362a457195..0000000000
--- a/docs/content/docs/fleets/reference/namespace.mdx
+++ /dev/null
@@ -1,69 +0,0 @@
----
-title: "Namespace"
-description: "The account-owned scope every pool, template, claim and secret lives in."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: libs/fleet/backend/docs/swagger.json
- Version: 0.4.1
-*/}
-
-On this page: [REST](#rest)
-
-## REST
-
-### Create a namespace
-
-```http
-POST /api/namespaces
-```
-
-Body (`application/json`):
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `name` | `string` | none | Namespace name: a DNS label. |
-
-Returns: `201` with an object with `createdAt` (string), `labels` (map of string), `name` (string), `status` (string).
-
-Errors: [`400`](/fleets/reference/errors#http-400), [`401`](/fleets/reference/errors#http-401), [`409`](/fleets/reference/errors#http-409), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### List namespaces
-
-```http
-GET /api/namespaces
-```
-
-Returns: `200` with an array; each item is an object with `createdAt` (string), `labels` (map of string), `name` (string), `status` (string).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Get a namespace
-
-```http
-GET /api/namespaces/{name}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Returns: `200` with an object with `createdAt` (string), `labels` (map of string), `name` (string), `status` (string).
-
-Errors: [`400`](/fleets/reference/errors#http-400), [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`404`](/fleets/reference/errors#http-404), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Delete a namespace
-
-```http
-DELETE /api/namespaces/{name}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Returns: `204`. No Content.
-
-Errors: [`400`](/fleets/reference/errors#http-400), [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`404`](/fleets/reference/errors#http-404), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
diff --git a/docs/content/docs/fleets/reference/pool.mdx b/docs/content/docs/fleets/reference/pool.mdx
deleted file mode 100644
index 239ab8a405..0000000000
--- a/docs/content/docs/fleets/reference/pool.mdx
+++ /dev/null
@@ -1,287 +0,0 @@
----
-title: "Pool"
-description: "Warm capacity: how many sandboxes of one template Fleet keeps ready to claim."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: cua-fleet fleet-docs-dump (osgym.cua.ai CRDs); libs/fleet/sdk/src (routes, methods); libs/fleet/backend/docs/swagger.json; cua-sdk src/native/fleet.rs; terraform-provider-fleets schema
- Version: 0.4.1
-*/}
-
-On this page: [Object](#the-pool-object) · [REST](#rest) · [SDK](#sdk) · [Terraform](#terraform)
-
-## The pool object
-
-`apiVersion: osgym.cua.ai/v1alpha1`, `kind: OSGymSandboxWarmPool`, in the pool's namespace. Plural `osgymsandboxwarmpools`, short name `oswp`. `metadata` is standard Kubernetes object metadata (`name`, `namespace`, `labels`).
-
-### Spec
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `spec.autoscaling` | `object` | none | Claim-driven autoscaling. When set, Fleet sizes the pool from its live claims (Pending and Bound) and owns `spec.replicas`: a Pending claim grows the pool, deleting claims shrinks it. Absent: `spec.replicas` is a static size. |
-| `spec.autoscaling.initialPoolSize` | `integer` | `0` | Warm head start: `spec.replicas` starts here when the pool is created, so the first claims bind without a cold start. It then follows claim demand, never below `minPoolSize`. At least 0. |
-| `spec.autoscaling.maxPoolSize` | `integer` | `50` | Most sandboxes the pool scales to. At least 1. |
-| `spec.autoscaling.minPoolSize` | `integer` | `0` | Fewest warm sandboxes kept while autoscaling. `0` lets the pool scale to zero when there are no claims. At least 0. |
-| `spec.idleTtlSeconds` | `integer` | none | Idle TTL in seconds. The pool-operator deletes the pool once it has had no Pending or Bound claims for this long, measured from status.lastActivityTime (or creation when no claim was ever made), when OSGYM_POOL_LIFECYCLE_MODE is enforce. When absent, the pool is never reaped for being idle. At least 0. |
-| `spec.replicas` | `integer` | required | Warm sandboxes to keep ready. With `autoscaling`, Fleet sets it. At least 0. |
-| `spec.sandboxTemplateRef` | `object` | required | The template the pool's sandboxes run. |
-| `spec.sandboxTemplateRef.name` | `string` | required | Name of the OSGymSandboxTemplate to use. |
-| `spec.ttlPolicy` | `"Retain" \| "Cascade"` | none | What expiry of ttlSecondsAfterCreated or idleTtlSeconds deletes. Retain (the behaviour when absent) deletes only the pool. Cascade also deletes the pool's dead unbound claims (TTL passed and older than max(900s, bindDeadline)); it never deletes Bound claims, the namespace or volumes. |
-| `spec.ttlSecondsAfterCreated` | `integer` | none | Creation-age TTL in seconds. When absent, the resource is not automatically reaped based on age. At least 0. |
-
-### Status
-
-Set by Fleet; read-only.
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `status.lastActivityTime` | `string` | none | When a claim against this pool was last created, bound or released. The idle TTL (spec.idleTtlSeconds) counts from here. |
-| `status.lastClaimedAt` | `string` | none | When a claim last bound a Sandbox from this pool. |
-| `status.readyReplicas` | `integer` | none | Sandboxes ready to be claimed. |
-| `status.replicas` | `integer` | none | Sandboxes the pool currently owns. |
-| `status.selector` | `string` | none | Label selector for the pool's OSGymSandboxes. |
-
-### Example
-
-What the SDK sends for a default pool of the cua Linux image (`PoolSpec::new`, built by `cua-fleet`).
-
-```json
-{
- "apiVersion": "osgym.cua.ai/v1alpha1",
- "kind": "OSGymSandboxWarmPool",
- "metadata": {
- "name": "my-pool",
- "namespace": "my-pool"
- },
- "spec": {
- "replicas": 1,
- "sandboxTemplateRef": {
- "name": "my-pool"
- }
- }
-}
-```
-
-## REST
-
-### Create pool
-
-```http
-POST /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxwarmpools
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-
-Body: the [pool object](#the-pool-object) (`application/json`).
-
-Returns: `200`, `201`, `202` with the [pool object](#the-pool-object).
-
-The SDK first creates the namespace named after the pool ([Create a namespace](/fleets/reference/namespace#create-a-namespace)) and deletes it again if the pool is refused.
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### List pools
-
-```http
-GET /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxwarmpools
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-
-Returns: `200` with `{"items": [...]}`, a list of the [pool object](#the-pool-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Get pool
-
-```http
-GET /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{name}/osgymsandboxwarmpools/{name}
-```
-
-A pool's namespace is its name, so the name fills both slots.
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Returns: `200` with the [pool object](#the-pool-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Update pool
-
-```http
-PATCH /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxwarmpools/{name}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Body: a JSON merge patch of the [pool object](#the-pool-object) (`application/merge-patch+json`).
-
-Returns: `200` with the [pool object](#the-pool-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Delete pool
-
-```http
-DELETE /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxwarmpools/{name}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Returns: `200`, `202`, `204` with no body.
-
-`404` is treated as success: the object is already gone.
-
-The SDK then deletes the namespace, with everything left in it.
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-## SDK
-
-Methods of the `Fleet` handle (`cua.fleet()`), with signatures in every language in the [Cua SDK reference](/cua-sdk/reference).
-
-| Method | Returns | Description |
-| --- | --- | --- |
-| [`Fleet.apply_pool(spec)`](/cua-sdk/reference/fleet#fleetapply_pool) | `FleetPool` | Deprecated: use `Fleet::apply`. |
-| [`Fleet.apply(name, spec, options)`](/cua-sdk/reference/fleet#fleetapply) | `FleetPool` | Reconciles pool `name` (= namespace = template) to run `spec` with `options`: the one pool writer (rolls a new pool back if the template fails). |
-| [`Fleet.get_pool(name)`](/cua-sdk/reference/fleet#fleetget_pool) | `FleetPool` | Looks up a pool. |
-| [`Fleet.list_pools(namespace)`](/cua-sdk/reference/fleet#fleetlist_pools) | `FleetPool[]` | Lists pools in a namespace. |
-| [`Fleet.set_pool_replicas(name, replicas)`](/cua-sdk/reference/fleet#fleetset_pool_replicas) | `FleetPool` | Sets warm replicas (0 suspends). |
-| [`Fleet.wait_pool_ready(name, timeout_ms)`](/cua-sdk/reference/fleet#fleetwait_pool_ready) | `FleetPool` | Waits for at least one ready replica. |
-| [`Fleet.export_pool(name)`](/cua-sdk/reference/fleet#fleetexport_pool) | `FleetPoolExport` | Reads pool `name` back as the shared model, with its `fleets_pool` Terraform block. |
-| [`Fleet.delete_pool(name)`](/cua-sdk/reference/fleet#fleetdelete_pool) | none | Deletes a pool, its namespace and its same-named template. |
-| `Fleet.ephemeral_pool_name()` | `string` | A random ephemeral pool name (`cua-eph-<hex>`). |
-| `Fleet.pools()` | `FleetPools` | Managed pools (list, gc). |
-| [`FleetPools.list()`](/cua-sdk/reference/fleet#fleetpoolslist) | `FleetManagedPool[]` | This account's managed pools. |
-| [`FleetPools.gc(idle_seconds)`](/cua-sdk/reference/fleet#fleetpoolsgc) | `FleetGcReport` | Deletes managed pools idle for `idle_seconds` (default 1800) and stuck Pending/Failed managed claims past their TTL. |
-| [`FleetPools.gc_pools(names, idle_seconds)`](/cua-sdk/reference/fleet#fleetpoolsgc_pools) | `FleetGcReport` | `FleetPools::gc` restricted to the named managed pools: each is deleted (with its namespace) once it has no claims and has been idle for `idle_seconds` (default 0, i.e. now). |
-
-## Terraform
-
-Resource `fleets_pool` of the [`trycua/fleets` provider](/fleets/reference/terraform). A Cua Fleet computer-use pool: an OSGymSandboxWarmPool and its OSGymSandboxTemplate. The pool name also owns its same-named namespace.
-
-{/* Example source: fleets/guides/terraform.mdx#main-tf (tested by the docs terraform lane) */}
-
-```hcl title="main.tf"
-terraform {
- required_providers {
- fleets = {
- source = "trycua/fleets"
- version = "0.2.0"
- }
- }
-}
-
-provider "fleets" {
- endpoint = "https://run.cua.ai"
-}
-
-resource "fleets_pool" "linux" {
- name = "linux-pool"
- cpu_cores = 4
- memory = "8Gi"
- container_disk_image = "ghcr.io/trycua/linux:24.04-disk"
- runtime = "kubevirt"
- firmware = "bios"
-
- service {
- name = "env"
- target_port = 3211
- protocol = "TCP"
- }
-
- autoscaling {
- min_pool_size = 0
- initial_pool_size = 1
- max_pool_size = 5
- }
-}
-
-output "linux_pool" {
- value = {
- name = fleets_pool.linux.name
- namespace = fleets_pool.linux.namespace
- target_replicas = fleets_pool.linux.replicas
- current_replicas = fleets_pool.linux.current_replicas
- ready_replicas = fleets_pool.linux.ready_replicas
- }
-}
-```
-
-### Arguments
-
-Exactly one of `replicas` or `autoscaling` is required.
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `name` | `string` | required | Pool and namespace DNS label. Changing it replaces the resource. 1 to 63 characters. Matches `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`. |
-| `replicas` | `number` | none | Static desired warm pool size. Exactly one of `replicas` or `autoscaling` must be configured. In autoscaling mode, do not configure it; after apply and refresh it reports the current pool target. At least 0. |
-| `cpu_cores` | `number` | required | Virtual CPUs per sandbox. At least 1. |
-| `memory` | `string` | required | Kubernetes memory quantity per sandbox. |
-| `container_disk_image` | `string` | required | OCI containerDisk or runtime image. |
-| `image_pull_secret` | `string` | none | Optional image pull secret. Omit it for an anonymous public-image pull. |
-| `runtime` | `string` | `"kubevirt"` | `kubevirt`, `macos`, or `gvisor`; defaults to `kubevirt`. |
-| `firmware` | `string` | `"bios"` | `bios` or `efi`; defaults to `bios`. |
-| `readiness_probe_json` | `string (JSON)` | none | Kubernetes probe objects encoded as JSON. |
-| `liveness_probe_json` | `string (JSON)` | none | Kubernetes probe objects encoded as JSON. |
-| `command` | `list(string)` | none | Entrypoint command list (replaces the image entrypoint). Pod runtimes (`gvisor`, `macos`) run it; KubeVirt ignores it. |
-| `claim_secrets` | `bool` | none | Opt in to claim-scoped secret delivery at `/run/cua` (the per-claim env token and a claim's `secretRef`). Claims with a `secretRef` fail on pools without it. |
-| `ttl_seconds_after_created` | `number` | none | Delete the pool this many seconds after it was created. Omit it to never reap by age. 0 to 4294967295. |
-| `idle_ttl_seconds` | `number` | none | Delete the pool after this many seconds with no Pending or Bound claims. Omit it to never reap for idleness. 0 to 4294967295. |
-| `ttl_policy` | `string` | none | What a TTL expiry deletes: `Retain` (the pool only, the behavior when omitted) or `Cascade` (also the pool's dead unbound claims; never Bound claims, the namespace or volumes). |
-
-### `service` block
-
-Repeatable block. Repeatable service with `name`, `target_port`, and optional `protocol`.
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `service.name` | `string` | required | Service name suffix (sandbox name is prepended). |
-| `service.target_port` | `number` | required | Port on the VM pod to forward to. 1 to 65535. |
-| `service.protocol` | `string` | `"TCP"` | `TCP` or `UDP`. |
-
-### `autoscaling` block
-
-Block. Claim-driven autoscaling limits. Exactly one of `replicas` or `autoscaling` is required.
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `autoscaling.min_pool_size` | `number` | `0` | Minimum warm pool size while autoscaling is enabled. At least 0. |
-| `autoscaling.initial_pool_size` | `number` | `0` | Initial pool target when autoscaling starts. At least 0. |
-| `autoscaling.max_pool_size` | `number` | `50` | Maximum autoscaled pool size; defaults to `50` when omitted. At least 1. |
-
-### Attributes
-
-Read-only, set by the provider.
-
-| Attribute | Type | Description |
-| --- | --- | --- |
-| `id` | `string` | The pool name. |
-| `namespace` | `string` | The pool's namespace (the pool name). |
-| `template_name` | `string` | Name of the OSGymSandboxTemplate backing this pool. |
-| `current_replicas` | `number` | Sandboxes the warm pool currently owns. |
-| `ready_replicas` | `number` | Sandboxes that are ready to be claimed. |
-
-`replicas` is also set in autoscaling mode: it reports the current pool target.
-
-### Import
-
-Import IDs are pool names.
-
-```shell
-terraform import fleets_pool.linux training-linux
-```
diff --git a/docs/content/docs/fleets/reference/sandbox.mdx b/docs/content/docs/fleets/reference/sandbox.mdx
deleted file mode 100644
index b5c31778a1..0000000000
--- a/docs/content/docs/fleets/reference/sandbox.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: "Sandbox"
-description: "One running machine of a pool, bound to at most one claim."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: cua-fleet fleet-docs-dump (osgym.cua.ai CRDs); cua-sdk src/native/fleet.rs
- Version: 0.4.1
-*/}
-
-A sandbox is created by its pool, never directly. `status.sandbox` of a bound [claim](/fleets/reference/claim) names it; the SDK returns it as a `FleetSandbox` (namespace, claim, name and services).
-
-On this page: [Object](#the-sandbox-object) · [SDK](#sdk)
-
-## The sandbox object
-
-`apiVersion: osgym.cua.ai/v1alpha1`, `kind: OSGymSandbox`, in the pool's namespace. Plural `osgymsandboxes`, short name `osbx`. `metadata` is standard Kubernetes object metadata (`name`, `namespace`, `labels`).
-
-### Spec
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `spec.vmTemplate` | `object` | required | What each sandbox runs. |
-| `spec.vmTemplate.args` | `string[]` | none | Arguments (Kubernetes args semantics: they replace the image CMD and follow vmTemplate.command). Runs on pod runtimes (gvisor/macos). On runtime kubevirt it needs processMode: Run and a command (a VM image has no entrypoint to pass them to); without Run the gateway and the pool-operator refuse it. |
-| `spec.vmTemplate.claimSecrets` | `boolean` | none | Opt in to claim-scoped secret delivery (OSGymSandboxClaim spec.secretRef). The pool-operator gives every sandbox an operator-owned Secret, empty while the sandbox is warm, fills it when a claim binds and wipes it on release, so a warm sandbox receives its claimant's secrets without a restart. Pod runtimes mount it read-only as a directory (never subPath) at /run/cua, root-owned, mode 0600; the image keeps its default root user, and its root token-sync helper hands the token to a non-root driver. KubeVirt shares it over virtiofs as tag cua-claim-secrets (the EnableVirtioFsConfigVolumes feature gate is GA from KubeVirt v1.8; older KubeVirt needs it enabled); the guest image mounts that tag read-only at /run/cua. cua-env-driver images enable their await-token mode only when /run/cua is a mount point, so the key env-token becomes /run/cua/env-token. Claims with a secretRef fail on templates without this flag. |
-| `spec.vmTemplate.command` | `string[]` | none | `gvisor` and `macos` only: entrypoint of the sandbox container, overriding the image's. |
-| `spec.vmTemplate.containerDiskImage` | `string` | required | The image: a containerDisk for `kubevirt`, a container image for `gvisor` and `macos`. |
-| `spec.vmTemplate.cpuCores` | `integer` | `4` | Virtual CPUs per sandbox. At least 1. |
-| `spec.vmTemplate.env` | `map of string` | none | Plain environment variables for the sandbox's command (not for secrets: the values are stored in the template and visible to anyone who can read it). Names must match ^[A-Za-z_][A-Za-z0-9_]*$. $(NAME) references in command/args expand as in Kubernetes. Pod runtimes (gvisor/macos) set them on the sandbox container. On runtime kubevirt they need processMode: Run and go to /etc/cua/env (root, 0600) and the command's environment; values must be single-line there. Without Run the gateway and the pool-operator refuse env on kubevirt. |
-| `spec.vmTemplate.firmware` | `"bios" \| "efi"` | `"bios"` | VM firmware for `kubevirt`: `efi` for UEFI-only images such as Windows, `bios` for the Linux images. |
-| `spec.vmTemplate.imagePullPolicy` | `"Always" \| "IfNotPresent" \| "Never"` | none | `gvisor` and `macos` only: when to pull the image (default `IfNotPresent`). |
-| `spec.vmTemplate.imagePullSecret` | `string` | none | Secret in the pool's namespace with registry credentials for a private image. Omit it for a public image. |
-| `spec.vmTemplate.memory` | `string` | `"4Gi"` | Memory per sandbox, as a Kubernetes quantity such as `8Gi`. |
-| `spec.vmTemplate.nestedVirtualization` | `boolean` | `false` | Expose hardware virtualization (KVM) inside the VM. |
-| `spec.vmTemplate.nodeSelector` | `map of string` | none | `gvisor` and `macos` only: node selector of the sandbox pod. Fleet's default fits the runtime. |
-| `spec.vmTemplate.oidc` | `object` | none | Workload identity: Fleet puts an OIDC access token for your account at `/var/run/cua/oidc/token` in the guest and keeps it fresh, so the workload can federate into AWS (`sts:AssumeRoleWithWebIdentity`) or any other provider that trusts the token. |
-| `spec.vmTemplate.oidc.awsRegion` | `string` | `"us-west-2"` | AWS region for AWS SDK calls in the guest. |
-| `spec.vmTemplate.oidc.awsRoleArn` | `string` | none | When set, the guest's AWS SDK assumes this role with the token (environment and `~/.aws/config` are set up). |
-| `spec.vmTemplate.oidc.credentialsSecret` | `string` | required | Secret in the pool's namespace holding the client credentials (`client_id`, `client_secret`) that mint the token. |
-| `spec.vmTemplate.oidc.refreshIntervalSeconds` | `integer` | `1800` | How often the guest refreshes the token (half its one-hour lifetime by default). At least 60. |
-| `spec.vmTemplate.oidc.tokenUrl` | `string` | required | Token endpoint that mints the workload token. |
-| `spec.vmTemplate.probes` | `object (any JSON)` | none | Kubernetes `readinessProbe` and `livenessProbe` for the VM, so a sandbox counts as ready only when the guest serves. |
-| `spec.vmTemplate.processMode` | `"Legacy" \| "Run"` | none | How command, args and env reach the sandbox. Absent or Legacy: unchanged behavior (pod runtimes run them; KubeVirt ignores command and refuses args and env). Run: every runtime runs them with the same semantics. Pod runtimes set them on the sandbox container; KubeVirt writes /etc/cua/env (0600), /etc/cua/command.sh (0700) and cua-command.service into the sandbox's cloud-init Secret, which the guest re-reads on every boot, so warm VMs get it on return-to-pool too. KubeVirt Run needs a Linux guest with cloud-init and systemd. |
-| `spec.vmTemplate.runtime` | `"kubevirt" \| "macos" \| "gvisor"` | `"kubevirt"` | `kubevirt`: each sandbox is a VM booted from `containerDiskImage`. `gvisor`: a gVisor container of the image. `macos`: a macOS sandbox. For `gvisor` and `macos`, `firmware`, `cpuCores` and `memory` are advisory. |
-| `spec.vmTemplate.runtimeClassName` | `string` | none | `gvisor` and `macos` only: RuntimeClass of the sandbox pod. Fleet's default fits the runtime. |
-| `spec.vmTemplate.services` | `object[]` | none | Ports each sandbox publishes, as a Service named `<sandbox>-<name>`. Reach them through service URLs. |
-| `spec.vmTemplate.services[].name` | `string` | required | Service name suffix (sandbox name is prepended). |
-| `spec.vmTemplate.services[].protocol` | `"TCP" \| "UDP"` | `"TCP"` | `TCP` or `UDP`. |
-| `spec.vmTemplate.services[].targetPort` | `integer` | required | Port in the sandbox. 1 to 65535. |
-| `spec.vmTemplate.tolerations` | `object (any JSON)[]` | none | `gvisor` and `macos` only: tolerations of the sandbox pod. Fleet's default fits the runtime. |
-
-### Status
-
-Set by Fleet; read-only.
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `status.message` | `string` | none | Human-readable detail, set when the OSGymSandbox is stuck (e.g. spec.vmTemplate.containerDiskImage missing). |
-| `status.phase` | `string` | none | `Pending`, `Ready` or `Terminating`. |
-| `status.ready` | `boolean` | none | Whether the sandbox is ready. |
-| `status.resetIssuedAt` | `string` | none | When Fleet began restarting the sandbox to return it to its pool. |
-| `status.resetVmiUid` | `string` | none | Identifies the VM instance that restart replaces. |
-| `status.runtime` | `string` | none | Runtime that provisioned the sandbox: `macos`, `gvisor`, or empty for `kubevirt`. |
-| `status.service` | `string` | none | In-cluster DNS name of the sandbox's Service. |
-| `status.vmName` | `string` | none | Name of the sandbox's VM (`kubevirt`). |
-
-## SDK
-
-Methods of the `Fleet` handle (`cua.fleet()`), with signatures in every language in the [Cua SDK reference](/cua-sdk/reference).
-
-| Method | Returns | Description |
-| --- | --- | --- |
-| [`Fleet.attach_claim(namespace, name)`](/cua-sdk/reference/fleet/claims#fleetattach_claim) | `FleetSandbox` | Waits for a named claim to bind. |
-| [`Fleet.service_url(sandbox, service)`](/cua-sdk/reference/fleet/claims#fleetservice_url) | `string` | The gateway URL of a sandbox service (needs the Fleet bearer). |
diff --git a/docs/content/docs/fleets/reference/secret.mdx b/docs/content/docs/fleets/reference/secret.mdx
deleted file mode 100644
index f82cb63628..0000000000
--- a/docs/content/docs/fleets/reference/secret.mdx
+++ /dev/null
@@ -1,77 +0,0 @@
----
-title: "Secret"
-description: "Secrets the SDK writes in a pool's namespace: a claim's env token and registry pull credentials."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: cua-fleet fleet-docs-dump (secrets)
- Version: 0.4.1
-*/}
-
-## Claim secret
-
-Every claim the SDK makes carries a fresh env token for the sandbox's cua-spacesd. The SDK writes it as an Opaque Secret `cua-claim-<claim>` (key `env-token`, label `osgym.cua.ai/claim: <claim>`), then creates the claim with `spec.secretRef` naming it. Fleet delivers it into the bound sandbox at `/run/cua/env-token`; the token never crosses the network to the guest. After the claim binds, the SDK waits up to 90 seconds for the guest to accept the token, then releases the claim with [`ClaimSecretsNotDelivered`](/fleets/reference/errors#claimsecretsnotdelivered).
-
-```json
-{
- "apiVersion": "v1",
- "data": {
- "env-token": "MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWYwMTIzNDU2Nzg5YWJjZGVmMDEyMzQ1Njc4OWFiY2RlZg=="
- },
- "kind": "Secret",
- "metadata": {
- "labels": {
- "osgym.cua.ai/claim": "claim-1"
- },
- "name": "cua-claim-claim-1",
- "namespace": "my-pool"
- },
- "type": "Opaque"
-}
-```
-
-## Registry pull secret
-
-Credentials for a private registry, written as a `kubernetes.io/dockerconfigjson` Secret `cua-registry-<16 hex>` (a hash of registry and user, so a new password updates the same Secret) and named by the template's `imagePullSecret`.
-
-```json
-{
- "apiVersion": "v1",
- "data": {
- ".dockerconfigjson": "eyJhdXRocyI6eyJnaGNyLmlvIjp7ImF1dGgiOiJiMk4wYjJOaGREbzhkRzlyWlc0KyIsInBhc3N3b3JkIjoiPHRva2VuPiIsInVzZXJuYW1lIjoib2N0b2NhdCJ9fX0="
- },
- "kind": "Secret",
- "metadata": {
- "labels": {
- "cua.ai/registry-secret": "true"
- },
- "name": "cua-registry-91c6584ad5bdef3a",
- "namespace": "my-pool"
- },
- "type": "kubernetes.io/dockerconfigjson"
-}
-```
-
-## REST
-
-Secrets are core Kubernetes objects behind the same proxy as the Fleet resources.
-
-### Create a secret
-
-```http
-POST /api/k8s/api/v1/namespaces/{namespace}/secrets
-```
-
-Body: the Secret. `409` means a Secret of that name exists (another claim attempt); the SDK does not overwrite it.
-
-### Delete a secret
-
-```http
-DELETE /api/k8s/api/v1/namespaces/{namespace}/secrets/{name}
-```
-
-`404` is treated as success. The SDK deletes a claim's Secret when it releases the claim.
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
diff --git a/docs/content/docs/fleets/reference/service-url.mdx b/docs/content/docs/fleets/reference/service-url.mdx
deleted file mode 100644
index 0abd9d66d3..0000000000
--- a/docs/content/docs/fleets/reference/service-url.mdx
+++ /dev/null
@@ -1,97 +0,0 @@
----
-title: "Service URL"
-description: "HTTP and WebSocket access to a sandbox's services, and shareable signed URLs."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: libs/fleet/backend/docs/swagger.json; cua-sdk src/native/fleet.rs
- Version: 0.4.1
-*/}
-
-On this page: [REST](#rest) · [SDK](#sdk)
-
-## REST
-
-### Call a service
-
-```http
-GET /api/svc/{namespace}/{service}/{path}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `service` | path | The Kubernetes Service of the sandbox service: `<sandbox>-<service>`. |
-| `path` | path | The upstream path, forwarded verbatim (it must start with `/`). Optional. |
-
-Returns: `200`. Upstream response.
-
-Errors: [`400`](/fleets/reference/errors#http-400), [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Create a signed URL
-
-```http
-POST /api/signed-service-urls/{namespace}
-```
-
-Creates a temporary bearer link for one logical sandbox service.
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-
-Body (`application/json`):
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `claim` | `string` | required | The claim that holds the sandbox. |
-| `expiresInSeconds` | `integer` | required | Lifetime of the URL, in seconds. 60 to 86400. |
-| `label` | `string` | none | A label for the URL, at most 120 UTF-8 bytes. At most 120 characters. |
-| `logicalService` | `string` | required | The service as the template names it, for example `env`. |
-| `sandbox` | `string` | required | The sandbox name (`status.sandbox.name` of the claim). |
-| `service` | `string` | required | The sandbox's Service: `<sandbox>-<logicalService>`. |
-
-Returns: `201` with an object with `claim` (string), `createdAt` (string), `expiresAt` (string), `id` (string), `label` (string), `logicalService` (string), `namespace` (string), `revokedAt` (string), `sandbox` (string), `service` (string), `url` (string).
-
-Errors: [`400`](/fleets/reference/errors#http-400), [`401`](/fleets/reference/errors#http-401), [`404`](/fleets/reference/errors#http-404), [`500`](/fleets/reference/errors#http-500), [`503`](/fleets/reference/errors#http-503) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### List signed URLs
-
-```http
-GET /api/signed-service-urls/{namespace}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `claim` | query | The claim name. |
-
-Returns: `200` with an array; each item is an object with `claim` (string), `createdAt` (string), `expiresAt` (string), `id` (string), `label` (string), `logicalService` (string), `namespace` (string), `revokedAt` (string), `sandbox` (string), `service` (string), `url` (string).
-
-Errors: [`400`](/fleets/reference/errors#http-400), [`401`](/fleets/reference/errors#http-401), [`500`](/fleets/reference/errors#http-500), [`503`](/fleets/reference/errors#http-503) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Revoke a signed URL
-
-```http
-DELETE /api/signed-service-urls/{namespace}/{id}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `id` | path | The object id. |
-
-Returns: `204`. No Content.
-
-Errors: [`400`](/fleets/reference/errors#http-400), [`401`](/fleets/reference/errors#http-401), [`404`](/fleets/reference/errors#http-404), [`500`](/fleets/reference/errors#http-500), [`503`](/fleets/reference/errors#http-503) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-## SDK
-
-Methods of the `Fleet` handle (`cua.fleet()`), with signatures in every language in the [Cua SDK reference](/cua-sdk/reference).
-
-| Method | Returns | Description |
-| --- | --- | --- |
-| [`Fleet.service_url(sandbox, service)`](/cua-sdk/reference/fleet/claims#fleetservice_url) | `string` | The gateway URL of a sandbox service (needs the Fleet bearer). |
-| [`Fleet.create_signed_service_url(sandbox, service, label, expires_in_seconds)`](/cua-sdk/reference/fleet/claims#fleetcreate_signed_service_url) | `FleetSignedUrl` | Mints a signed, shareable service URL. |
diff --git a/docs/content/docs/fleets/reference/template.mdx b/docs/content/docs/fleets/reference/template.mdx
deleted file mode 100644
index 76a2192d04..0000000000
--- a/docs/content/docs/fleets/reference/template.mdx
+++ /dev/null
@@ -1,199 +0,0 @@
----
-title: "Template"
-description: "What each sandbox of a pool runs: image, runtime, size, services and probes."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: cua-fleet fleet-docs-dump (osgym.cua.ai CRDs); libs/fleet/sdk/src (routes, methods); libs/fleet/backend/docs/swagger.json; cua-sdk src/native/fleet.rs; terraform-provider-fleets schema
- Version: 0.4.1
-*/}
-
-On this page: [Object](#the-template-object) · [REST](#rest) · [SDK](#sdk) · [Terraform](#terraform)
-
-## The template object
-
-`apiVersion: osgym.cua.ai/v1alpha1`, `kind: OSGymSandboxTemplate`, in the pool's namespace. Plural `osgymsandboxtemplates`, short name `osbt`. `metadata` is standard Kubernetes object metadata (`name`, `namespace`, `labels`).
-
-### Spec
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `spec.vmTemplate` | `object` | required | What each sandbox runs. |
-| `spec.vmTemplate.args` | `string[]` | none | Arguments (Kubernetes args semantics: they replace the image CMD and follow vmTemplate.command). Runs on pod runtimes (gvisor/macos). On runtime kubevirt it needs processMode: Run and a command (a VM image has no entrypoint to pass them to); without Run the gateway and the pool-operator refuse it. |
-| `spec.vmTemplate.claimSecrets` | `boolean` | none | Opt in to claim-scoped secret delivery (OSGymSandboxClaim spec.secretRef). The pool-operator gives every sandbox an operator-owned Secret, empty while the sandbox is warm, fills it when a claim binds and wipes it on release, so a warm sandbox receives its claimant's secrets without a restart. Pod runtimes mount it read-only as a directory (never subPath) at /run/cua, root-owned, mode 0600; the image keeps its default root user, and its root token-sync helper hands the token to a non-root driver. KubeVirt shares it over virtiofs as tag cua-claim-secrets (the EnableVirtioFsConfigVolumes feature gate is GA from KubeVirt v1.8; older KubeVirt needs it enabled); the guest image mounts that tag read-only at /run/cua. cua-env-driver images enable their await-token mode only when /run/cua is a mount point, so the key env-token becomes /run/cua/env-token. Claims with a secretRef fail on templates without this flag. |
-| `spec.vmTemplate.command` | `string[]` | none | `gvisor` and `macos` only: entrypoint of the sandbox container, overriding the image's. |
-| `spec.vmTemplate.containerDiskImage` | `string` | required | The image: a containerDisk for `kubevirt`, a container image for `gvisor` and `macos`. |
-| `spec.vmTemplate.cpuCores` | `integer` | `4` | Virtual CPUs per sandbox. At least 1. |
-| `spec.vmTemplate.env` | `map of string` | none | Plain environment variables for the sandbox's command (not for secrets: the values are stored in the template and visible to anyone who can read it). Names must match ^[A-Za-z_][A-Za-z0-9_]*$. $(NAME) references in command/args expand as in Kubernetes. Pod runtimes (gvisor/macos) set them on the sandbox container. On runtime kubevirt they need processMode: Run and go to /etc/cua/env (root, 0600) and the command's environment; values must be single-line there. Without Run the gateway and the pool-operator refuse env on kubevirt. |
-| `spec.vmTemplate.firmware` | `"bios" \| "efi"` | `"bios"` | VM firmware for `kubevirt`: `efi` for UEFI-only images such as Windows, `bios` for the Linux images. |
-| `spec.vmTemplate.imagePullPolicy` | `"Always" \| "IfNotPresent" \| "Never"` | none | `gvisor` and `macos` only: when to pull the image (default `IfNotPresent`). |
-| `spec.vmTemplate.imagePullSecret` | `string` | none | Secret in the pool's namespace with registry credentials for a private image. Omit it for a public image. |
-| `spec.vmTemplate.memory` | `string` | `"4Gi"` | Memory per sandbox, as a Kubernetes quantity such as `8Gi`. |
-| `spec.vmTemplate.nestedVirtualization` | `boolean` | `false` | Expose hardware virtualization (KVM) inside the VM. |
-| `spec.vmTemplate.nodeSelector` | `map of string` | none | `gvisor` and `macos` only: node selector of the sandbox pod. Fleet's default fits the runtime. |
-| `spec.vmTemplate.oidc` | `object` | none | Workload identity: Fleet puts an OIDC access token for your account at `/var/run/cua/oidc/token` in the guest and keeps it fresh, so the workload can federate into AWS (`sts:AssumeRoleWithWebIdentity`) or any other provider that trusts the token. |
-| `spec.vmTemplate.oidc.awsRegion` | `string` | `"us-west-2"` | AWS region for AWS SDK calls in the guest. |
-| `spec.vmTemplate.oidc.awsRoleArn` | `string` | none | When set, the guest's AWS SDK assumes this role with the token (environment and `~/.aws/config` are set up). |
-| `spec.vmTemplate.oidc.credentialsSecret` | `string` | required | Secret in the pool's namespace holding the client credentials (`client_id`, `client_secret`) that mint the token. |
-| `spec.vmTemplate.oidc.refreshIntervalSeconds` | `integer` | `1800` | How often the guest refreshes the token (half its one-hour lifetime by default). At least 60. |
-| `spec.vmTemplate.oidc.tokenUrl` | `string` | required | Token endpoint that mints the workload token. |
-| `spec.vmTemplate.probes` | `object (any JSON)` | none | Kubernetes `readinessProbe` and `livenessProbe` for the VM, so a sandbox counts as ready only when the guest serves. |
-| `spec.vmTemplate.processMode` | `"Legacy" \| "Run"` | none | How command, args and env reach the sandbox. Absent or Legacy: unchanged behavior (pod runtimes run them; KubeVirt ignores command and refuses args and env). Run: every runtime runs them with the same semantics. Pod runtimes set them on the sandbox container; KubeVirt writes /etc/cua/env (0600), /etc/cua/command.sh (0700) and cua-command.service into the sandbox's cloud-init Secret, which the guest re-reads on every boot, so warm VMs get it on return-to-pool too. KubeVirt Run needs a Linux guest with cloud-init and systemd. |
-| `spec.vmTemplate.runtime` | `"kubevirt" \| "macos" \| "gvisor"` | `"kubevirt"` | `kubevirt`: each sandbox is a VM booted from `containerDiskImage`. `gvisor`: a gVisor container of the image. `macos`: a macOS sandbox. For `gvisor` and `macos`, `firmware`, `cpuCores` and `memory` are advisory. |
-| `spec.vmTemplate.runtimeClassName` | `string` | none | `gvisor` and `macos` only: RuntimeClass of the sandbox pod. Fleet's default fits the runtime. |
-| `spec.vmTemplate.services` | `object[]` | none | Ports each sandbox publishes, as a Service named `<sandbox>-<name>`. Reach them through service URLs. |
-| `spec.vmTemplate.services[].name` | `string` | required | Service name suffix (sandbox name is prepended). |
-| `spec.vmTemplate.services[].protocol` | `"TCP" \| "UDP"` | `"TCP"` | `TCP` or `UDP`. |
-| `spec.vmTemplate.services[].targetPort` | `integer` | required | Port in the sandbox. 1 to 65535. |
-| `spec.vmTemplate.tolerations` | `object (any JSON)[]` | none | `gvisor` and `macos` only: tolerations of the sandbox pod. Fleet's default fits the runtime. |
-
-### Fields the SDK adds
-
-Written as JSON beyond the published schema; Fleet reads them.
-
-| Field | Type | Description |
-| --- | --- | --- |
-| `spec.vmTemplate.claimSecrets` | `boolean` | Opts the template into per-claim Secrets: the Secret a claim names in `spec.secretRef` is delivered into the bound sandbox at `/run/cua/env-token`. |
-| `spec.vmTemplate.env` | `map of string` | Environment of the sandbox process. |
-| `spec.vmTemplate.args` | `string[]` | Arguments of the sandbox process. |
-| `spec.vmTemplate.sidecars` | `object[]` | Containers that run next to the sandbox, on every runtime (at most 8). They reach the sandbox at host `main`. |
-| `spec.vmTemplate.processMode` | `"Legacy" \| "Run"` | `Legacy`: pod runtimes run `command`, `args` and `env`; KubeVirt ignores `command` and refuses `args` and `env`. `Run`: every runtime runs them (KubeVirt through cloud-init). |
-
-### Example
-
-What the SDK sends for a default pool of the cua Linux image (`PoolSpec::new`, built by `cua-fleet`).
-
-```json
-{
- "apiVersion": "osgym.cua.ai/v1alpha1",
- "kind": "OSGymSandboxTemplate",
- "metadata": {
- "name": "my-pool",
- "namespace": "my-pool"
- },
- "spec": {
- "vmTemplate": {
- "containerDiskImage": "ghcr.io/trycua/linux:24.04-disk",
- "runtime": "kubevirt",
- "services": [
- {
- "name": "env",
- "protocol": "TCP",
- "targetPort": 3211
- }
- ]
- }
- }
-}
-```
-
-## REST
-
-### Create template
-
-```http
-POST /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxtemplates
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-
-Body: the [template object](#the-template-object) (`application/json`).
-
-Returns: `200`, `201`, `202` with the [template object](#the-template-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### List templates
-
-```http
-GET /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxtemplates
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-
-Returns: `200` with `{"items": [...]}`, a list of the [template object](#the-template-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Get template
-
-```http
-GET /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxtemplates/{name}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Returns: `200` with the [template object](#the-template-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Update template
-
-```http
-PATCH /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxtemplates/{name}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Body: a JSON merge patch of the [template object](#the-template-object) (`application/merge-patch+json`).
-
-Returns: `200` with the [template object](#the-template-object).
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-### Delete template
-
-```http
-DELETE /api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/osgymsandboxtemplates/{name}
-```
-
-| Parameter | In | Description |
-| --- | --- | --- |
-| `namespace` | path | The pool's namespace. A pool, its namespace and its template share one name. |
-| `name` | path | The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters). |
-
-Returns: `200`, `202`, `204` with no body.
-
-`404` is treated as success: the object is already gone.
-
-Errors: [`401`](/fleets/reference/errors#http-401), [`403`](/fleets/reference/errors#http-403), [`502`](/fleets/reference/errors#http-502) ([Errors](/fleets/reference/errors#http-status-codes)).
-
-## SDK
-
-Methods of the `Fleet` handle (`cua.fleet()`), with signatures in every language in the [Cua SDK reference](/cua-sdk/reference).
-
-| Method | Returns | Description |
-| --- | --- | --- |
-| [`Fleet.apply_pool_template(pool, spec)`](/cua-sdk/reference/fleet#fleetapply_pool_template) | none | Lays the set fields of `spec` over pool `pool`'s template and writes it (the pool's capacity is kept; a no-op when nothing differs). |
-| [`Fleet.check_pool_spec(pool, spec)`](/cua-sdk/reference/fleet#fleetcheck_pool_spec) | none | Compares the set fields of `spec` with pool `pool`'s template: `PoolSpecMismatch` (with a readable diff) when they differ. |
-| [`Fleet.list_templates(namespace)`](/cua-sdk/reference/fleet#fleetlist_templates) | `string[]` | Lists templates in a namespace as JSON resources. |
-
-## Terraform
-
-Terraform manages the template as part of its pool: [`fleets_pool`](/fleets/reference/pool#terraform) writes a template named `<pool>-template` from these arguments.
-
-| Terraform argument | Template field |
-| --- | --- |
-| [`cpu_cores`](/fleets/reference/pool#terraform) | `spec.vmTemplate.cpuCores` |
-| [`memory`](/fleets/reference/pool#terraform) | `spec.vmTemplate.memory` |
-| [`container_disk_image`](/fleets/reference/pool#terraform) | `spec.vmTemplate.containerDiskImage` |
-| [`image_pull_secret`](/fleets/reference/pool#terraform) | `spec.vmTemplate.imagePullSecret` |
-| [`runtime`](/fleets/reference/pool#terraform) | `spec.vmTemplate.runtime` |
-| [`firmware`](/fleets/reference/pool#terraform) | `spec.vmTemplate.firmware` |
-| [`readiness_probe_json`](/fleets/reference/pool#terraform) | `spec.vmTemplate.probes` |
-| [`liveness_probe_json`](/fleets/reference/pool#terraform) | `spec.vmTemplate.probes` |
-| [`command`](/fleets/reference/pool#terraform) | `spec.vmTemplate.command` |
-| [`claim_secrets`](/fleets/reference/pool#terraform) | `spec.vmTemplate.claimSecrets` |
-| [`service {}`](/fleets/reference/pool#terraform) | `spec.vmTemplate.services` |
diff --git a/docs/content/docs/fleets/reference/terraform.mdx b/docs/content/docs/fleets/reference/terraform.mdx
deleted file mode 100644
index 2fe30994ae..0000000000
--- a/docs/content/docs/fleets/reference/terraform.mdx
+++ /dev/null
@@ -1,45 +0,0 @@
----
-title: "Terraform provider"
-description: "The trycua/fleets provider: settings, environment variables and resources."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:fleet
- Source: terraform-provider-fleets internal/provider (provider.go, pool_generated.go), main.go
- Version: 0.4.1
-*/}
-
-The `trycua/fleets` provider manages Fleet pools. Install it from the Terraform Registry with `terraform init`; OpenTofu works the same with `tofu`.
-
-```hcl
-terraform {
- required_providers {
- fleets = {
- source = "trycua/fleets"
- }
- }
-}
-```
-
-## Provider arguments
-
-Use either `access_token`, or all three of `client_id`, `client_secret` and `token_url` (an [API key](/fleets/reference/api-key)). An argument wins over its environment variable.
-
-| Argument | Type | Default | Environment variable | Description |
-| --- | --- | --- | --- | --- |
-| `endpoint` | `string` | required | `CYCLOPS_ENDPOINT` | Fleet API base URL, for example `https://run.cua.ai`. |
-| `access_token` | `string` | none | `CYCLOPS_ACCESS_TOKEN` | Bearer token. Sensitive. |
-| `client_id` | `string` | none | `CYCLOPS_CLIENT_ID` | Fleet user-key client ID. |
-| `client_secret` | `string` | none | `CYCLOPS_CLIENT_SECRET` | Fleet user-key client secret. Sensitive. |
-| `token_url` | `string` | none | `CYCLOPS_TOKEN_URL` | OAuth token endpoint returned with the Fleet user key. |
-
-`CUA_CLIENT_ID`, `CUA_CLIENT_SECRET`, `FLEETS_TOKEN` and `cua auth login` do not configure the provider.
-
-## Resources
-
-| Resource | Manages | Reference |
-| --- | --- | --- |
-| `fleets_pool` | A Cua Fleet computer-use pool: an OSGymSandboxWarmPool and its OSGymSandboxTemplate. The pool name also owns its same-named namespace. | [Pool](/fleets/reference/pool#terraform) |
-
-The provider has no data sources.
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 2c9ebbde18..dc792783dc 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -7,7 +7,6 @@
"cua-sdk",
"cua-driver",
"spaces",
- "fleets",
"cua-bench",
"lume",
"cua-cli"
diff --git a/docs/content/docs/redirects.json b/docs/content/docs/redirects.json
index b1ea141150..65e6270f5e 100644
--- a/docs/content/docs/redirects.json
+++ b/docs/content/docs/redirects.json
@@ -9,7 +9,7 @@
"concepts/choose-a-cua-driver-integration": "cua-driver",
"concepts/cua-bench-task-lifecycle": "cua-bench",
"concepts/how-cua-driver-is-validated": "cua-driver/concepts/how-cua-driver-works",
- "concepts/how-fleet-images-work": "fleets/guides/images",
+ "concepts/how-fleet-images-work": "cua-sdk/guides/images",
"concepts/how-lume-expands-macos-disks": "lume/concepts/how-lume-works",
"concepts/how-lume-unattended-setup-works": "lume/concepts/how-lume-works",
"concepts/how-permission-policies-work": "cua-driver/guides/permissions",
@@ -17,7 +17,7 @@
"concepts/how-sip-works-in-lume-vms": "lume/concepts/how-lume-works",
"concepts/how-the-perception-extension-works": "cua-driver/concepts/perception-extension",
"concepts/linux-desktops-and-computer-use": "cua-driver/concepts/platform-support",
- "concepts/pools-claims-and-guest-services": "fleets",
+ "concepts/pools-claims-and-guest-services": "cua-sdk/guides/cua-cloud-ended",
"concepts/sandbox-lifecycle": "cua-sdk/guides/lifecycle",
"concepts/sdk-mcp-and-hosting": "cua-driver/concepts/how-cua-driver-works",
"concepts/the-no-foreground-contract": "cua-driver/concepts/how-cua-driver-works",
@@ -172,16 +172,38 @@
"cuabot": "cua-sdk/guides/migrate-from-deprecated-packages",
"cuabot/cuabot": "cua-sdk/guides/migrate-from-deprecated-packages",
"cuabot/install": "cua-sdk/guides/migrate-from-deprecated-packages",
- "fleets/concepts": "fleets",
- "fleets/concepts/how-fleet-images-work": "fleets/guides/images",
- "fleets/concepts/pools-claims-and-guest-services": "fleets",
- "fleets/guides/claim-a-sandbox": "fleets/guides/capacity-and-claims",
- "fleets/guides/configure-pool-with-terraform": "fleets/guides/terraform",
- "fleets/guides/create-fleet-capacity": "fleets/guides/capacity-and-claims",
- "fleets/guides/expire-pools-and-claims": "fleets/guides/capacity-and-claims",
- "fleets/guides/prepare-and-reference-a-fleet-image": "fleets/guides/images",
- "fleets/guides/recover-first-cloud-fleet": "fleets/guides/troubleshoot",
- "fleets/guides/troubleshoot-fleet-pools": "fleets/guides/troubleshoot",
+ "fleets/concepts": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/concepts/how-fleet-images-work": "cua-sdk/guides/images",
+ "fleets/concepts/pools-claims-and-guest-services": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/guides/claim-a-sandbox": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/guides/configure-pool-with-terraform": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/guides/create-fleet-capacity": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/guides/expire-pools-and-claims": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/guides/prepare-and-reference-a-fleet-image": "cua-sdk/guides/images",
+ "fleets/guides/recover-first-cloud-fleet": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/guides/troubleshoot-fleet-pools": "cua-sdk/guides/cua-cloud-ended",
+ "fleets": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/guides": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/guides/capacity-and-claims": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/guides/claim-secrets": "cua-sdk/guides/secrets",
+ "fleets/guides/images": "cua-sdk/guides/images",
+ "fleets/guides/sidecars": "cua-sdk/guides/sidecars",
+ "fleets/guides/terraform": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/guides/troubleshoot": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/guides/warm-pools": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/quickstart": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference/api-key": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference/claim": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference/errors": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference/image": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference/namespace": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference/pool": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference/sandbox": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference/secret": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference/service-url": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference/template": "cua-sdk/guides/cua-cloud-ended",
+ "fleets/reference/terraform": "cua-sdk/guides/cua-cloud-ended",
"how-to-guides": "",
"how-to-guides/agent-context/connect-your-agent-to-cua-docs": "docs-for-agents",
"how-to-guides/cua-bench/convert-benchmark-images": "cua-bench/guides/convert-benchmark-images",
@@ -229,23 +251,23 @@
"how-to-guides/recipes/prepare-an-exhibition-panel": "cua-driver/guides/recipes",
"how-to-guides/recipes/redact-and-annotate-a-pdf": "cua-driver/guides/recipes",
"how-to-guides/sandbox/choose-an-image": "cua-sdk/guides/images",
- "how-to-guides/sandbox/claim-a-sandbox": "fleets/guides/capacity-and-claims",
- "how-to-guides/sandbox/configure-pool-with-terraform": "fleets/guides/terraform",
+ "how-to-guides/sandbox/claim-a-sandbox": "cua-sdk/guides/cua-cloud-ended",
+ "how-to-guides/sandbox/configure-pool-with-terraform": "cua-sdk/guides/cua-cloud-ended",
"how-to-guides/sandbox/connect-directly": "cua-sdk/guides/desktop",
"how-to-guides/sandbox/connect-to-omarchy-with-novnc": "cua-sdk/guides/desktop",
"how-to-guides/sandbox/control-the-desktop-with-cua-driver": "cua-sdk/guides/desktop",
- "how-to-guides/sandbox/create-fleet-capacity": "fleets/guides/capacity-and-claims",
- "how-to-guides/sandbox/expire-pools-and-claims": "fleets/guides/capacity-and-claims",
+ "how-to-guides/sandbox/create-fleet-capacity": "cua-sdk/guides/cua-cloud-ended",
+ "how-to-guides/sandbox/expire-pools-and-claims": "cua-sdk/guides/cua-cloud-ended",
"how-to-guides/sandbox/images": "cua-sdk/guides/images",
"how-to-guides/sandbox/interactive-shell": "cua-sdk/guides/desktop",
"how-to-guides/sandbox/lifecycle": "cua-sdk/guides/lifecycle",
"how-to-guides/sandbox/manage-local-lifecycle": "cua-sdk/guides/local-runtimes",
"how-to-guides/sandbox/mcp": "cua-sdk/guides/services",
"how-to-guides/sandbox/minecraft": "cua-sdk/guides/agent-frameworks",
- "how-to-guides/sandbox/prepare-and-reference-a-fleet-image": "fleets/guides/images",
+ "how-to-guides/sandbox/prepare-and-reference-a-fleet-image": "cua-sdk/guides/images",
"how-to-guides/sandbox/private-registries": "cua-sdk/guides/images",
"how-to-guides/sandbox/quickstart": "cua-sdk/quickstart",
- "how-to-guides/sandbox/recover-first-cloud-fleet": "fleets/guides/troubleshoot",
+ "how-to-guides/sandbox/recover-first-cloud-fleet": "cua-sdk/guides/cua-cloud-ended",
"how-to-guides/sandbox/run-codex-native-computer-use-on-windows-fleet": "cua-sdk/guides/agent-frameworks",
"how-to-guides/sandbox/run-cursor-cloud-agent-on-fleet": "cua-sdk/guides/agent-frameworks",
"how-to-guides/sandbox/run-omarchy-on-cloud-fleet": "cua-sdk/guides/agent-frameworks",
@@ -258,7 +280,7 @@
"how-to-guides/sandbox/set-up-fleet-credentials": "cua-sdk/guides/cloud",
"how-to-guides/sandbox/share-service-with-signed-url": "cua-sdk/guides/services",
"how-to-guides/sandbox/sidecars": "cua-sdk/guides/sidecars",
- "how-to-guides/sandbox/troubleshoot-fleet-pools": "fleets/guides/troubleshoot",
+ "how-to-guides/sandbox/troubleshoot-fleet-pools": "cua-sdk/guides/cua-cloud-ended",
"how-to-guides/sandbox/tunneling": "cua-sdk/guides/services",
"how-to-guides/spaces/add-a-space": "spaces/guides/add-a-space",
"how-to-guides/spaces/install-cua": "spaces/quickstart",
diff --git a/docs/package.json b/docs/package.json
index 3603cc4e31..2efc742cea 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -29,8 +29,6 @@
"docs:generate:python": "tsx ../scripts/docs-generators/python-sdk.ts",
"docs:generate:cua-sdk-ts": "tsx ../scripts/docs-generators/typescript-sdk.ts",
"docs:generate:changelog": "tsx ../scripts/docs-generators/generate-changelog.ts",
- "docs:check:fleet": "tsx ../scripts/docs-generators/runner.ts --library fleet --check",
- "docs:generate:fleet": "tsx ../scripts/docs-generators/fleet.ts",
"docs:check:spaces": "tsx ../scripts/docs-generators/runner.ts --library spaces --check",
"docs:generate:spaces": "tsx ../scripts/docs-generators/spaces.ts",
"docs:check-links": "tsx scripts/check-links.ts",
diff --git a/docs/public/scripts/first-cloud-fleet/first-cloud-fleet.ts.txt b/docs/public/scripts/first-cloud-fleet/first-cloud-fleet.ts.txt
deleted file mode 100644
index 7b760593e9..0000000000
--- a/docs/public/scripts/first-cloud-fleet/first-cloud-fleet.ts.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-import { createHash } from 'node:crypto';
-import { writeFile } from 'node:fs/promises';
-import { embedded, Image, SandboxCreateOptions, type CuaLike } from '@trycua/cua';
-
-const SOURCE_TEXT = 'pear\napple\npear\nbanana\n';
-const SOURCE_PATH = '/tmp/first-cloud-fleet.txt';
-const SCREENSHOT = 'first-cloud-fleet.png';
-
-export async function runTutorial(cua: CuaLike, image: string): Promise<void> {
- // on: 'cloud' runs it in the cloud. No name: the claim is released
- // with the sandbox. The managed pool (cua-auto-*) is created for this image
- // on first use and reused afterwards.
- const sandbox = await cua.sandboxes().create(
- SandboxCreateOptions.create({ on: 'cloud', image, cpus: 4, memoryMb: 4096n })
- );
- try {
- console.log(`Claimed ${sandbox.name()}`);
- const env = await sandbox.spacesd(undefined);
-
- const bytes = new TextEncoder().encode(SOURCE_TEXT);
- await env.upload(SOURCE_PATH, bytes.buffer as ArrayBuffer, undefined);
- const result = await env.sh(`sha256sum ${SOURCE_PATH}`, undefined);
- if (!result.exit.success) throw new Error(new TextDecoder().decode(result.stderr));
-
- const guestDigest = new TextDecoder().decode(result.stdout).split(/\s+/)[0];
- const localDigest = createHash('sha256').update(SOURCE_TEXT).digest('hex');
- if (guestDigest !== localDigest) {
- throw new Error(`Verification failed: guest=${guestDigest} local=${localDigest}`);
- }
- console.log(`Verified SHA-256: ${guestDigest}`);
-
- const screenshot = await env.screenshot(undefined);
- await writeFile(SCREENSHOT, Buffer.from(screenshot.image));
- console.log(`Screenshot: ${SCREENSHOT}`);
- } finally {
- await sandbox.delete_();
- console.log('Claim released');
- }
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
- // Uses FLEETS_TOKEN or CUA_CLIENT_ID/CUA_CLIENT_SECRET, else the `cua auth login` session.
- const cua = embedded({ fleetFromSession: true });
- // Unset: the canonical Linux desktop, ghcr.io/trycua/linux:24.04.
- runTutorial(cua, process.env.CUA_FLEET_IMAGE ?? Image.linux()).catch((error: unknown) => {
- console.error(error);
- process.exitCode = 1;
- });
-}
diff --git a/docs/public/scripts/first-cloud-fleet/first_cloud_fleet.py b/docs/public/scripts/first-cloud-fleet/first_cloud_fleet.py
deleted file mode 100644
index 14753cd70e..0000000000
--- a/docs/public/scripts/first-cloud-fleet/first_cloud_fleet.py
+++ /dev/null
@@ -1,49 +0,0 @@
-# /// script
-# requires-python = ">=3.11,<3.14"
-# dependencies = [
-# "cua-sandbox==0.9.0",
-# ]
-# [[tool.uv.index]]
-# name = "cua-wheels"
-# url = "https://wheels.cua.ai/simple"
-# ///
-
-import asyncio
-import hashlib
-import os
-from pathlib import Path
-
-from cua_sandbox import Image, Sandbox
-
-SOURCE_TEXT = "pear\napple\npear\nbanana\n"
-SOURCE_PATH = "/tmp/first-cloud-fleet.txt"
-SCREENSHOT = Path("first-cloud-fleet.png")
-
-
-async def run_tutorial(image_ref: str | None = None) -> None:
- # Unset: the canonical Linux desktop, ghcr.io/trycua/linux:24.04.
- image = Image.from_registry(image_ref) if image_ref else Image.linux()
- # local=False runs it in the cloud. A managed pool (cua-auto-*) is created
- # for this image on first use and reused afterwards. Leaving the block
- # releases the claim.
- async with Sandbox.ephemeral(image, local=False, cpu=4, memory_mb=4096) as sandbox:
- print(f"Claimed {sandbox.claim_name} from pool {sandbox.pool_name}")
-
- await sandbox.files.write_text(SOURCE_PATH, SOURCE_TEXT)
- result = await sandbox.shell.run(f"sha256sum {SOURCE_PATH}")
- if not result.success:
- raise RuntimeError(result.stderr)
-
- guest_digest = result.stdout.split()[0]
- local_digest = hashlib.sha256(SOURCE_TEXT.encode()).hexdigest()
- if guest_digest != local_digest:
- raise RuntimeError(f"Verification failed: guest={guest_digest} local={local_digest}")
- print(f"Verified SHA-256: {guest_digest}")
-
- SCREENSHOT.write_bytes(await sandbox.screenshot())
- print(f"Screenshot: {SCREENSHOT.resolve()}")
- print("Claim released")
-
-
-if __name__ == "__main__":
- asyncio.run(run_tutorial(os.environ.get("CUA_FLEET_IMAGE")))
diff --git a/docs/scripts/fleet-task-pages.test.ts b/docs/scripts/fleet-task-pages.test.ts
deleted file mode 100644
index 7622b70a16..0000000000
--- a/docs/scripts/fleet-task-pages.test.ts
+++ /dev/null
@@ -1,84 +0,0 @@
-import assert from 'node:assert/strict';
-import { readFile, readdir } from 'node:fs/promises';
-import * as path from 'node:path';
-import test from 'node:test';
-
-const docs = path.resolve(__dirname, '..');
-const fleets = path.join(docs, 'content/docs/fleets');
-
-async function page(slug: string) {
- return readFile(path.join(fleets, `${slug}.mdx`), 'utf8');
-}
-
-async function mdxFiles(directory: string): Promise<string[]> {
- const entries = await readdir(directory, { withFileTypes: true });
- const nested = await Promise.all(
- entries.map((entry) => {
- const target = path.join(directory, entry.name);
- if (entry.isDirectory()) return mdxFiles(target);
- return entry.name.endsWith('.mdx') ? [target] : [];
- })
- );
- return nested.flat();
-}
-
-test('the capacity page uses persistent language tabs on the cua SDK', async () => {
- const source = await page('guides/capacity-and-claims');
- assert.match(source, /<Tabs groupId="language" persist items=\{\['Python', 'TypeScript'\]\}>/);
- assert.match(source, /<Tabs groupId="language" persist items=\{\['CLI', 'Python', 'TypeScript'\]\}>/);
- assert.match(source, /<Tab value="Python">/);
- assert.match(source, /<Tab value="TypeScript">/);
- assert.match(source, /@trycua\/cua/);
- assert.doesNotMatch(source, /computer-server|@trycua\/fleet/);
-});
-
-test('one page creates capacity, claims from it and expires it', async () => {
- const source = await page('guides/capacity-and-claims');
- assert.match(source, /Sandbox\.create\(image, local=False\)/);
- assert.match(source, /Pool\.apply\(\s*os\.environ/);
- assert.match(source, /Pool\.apply\(\s*fleet,/);
- assert.doesNotMatch(source, /applyPool|FleetPoolSpec/);
- assert.match(source, /Sandbox\.ephemeral/);
- assert.match(source, /cua sb create --on fleet --pool/);
- assert.match(source, /delete_\(\)/);
- assert.match(source, /## Expiry/);
- assert.match(source, /ttl_seconds_after_created/);
-});
-
-test('the Fleets guides are the advanced cloud tasks, in order', async () => {
- const meta = JSON.parse(await readFile(path.join(fleets, 'guides/meta.json'), 'utf8'));
- assert.deepEqual(meta.pages, [
- 'capacity-and-claims',
- 'warm-pools',
- 'terraform',
- 'images',
- 'sidecars',
- 'claim-secrets',
- 'troubleshoot',
- ]);
- for (const slug of meta.pages) await page(`guides/${slug}`);
-});
-
-test('no page retains a legacy language-specific capacity link', async () => {
- const files = await mdxFiles(path.join(docs, 'content/docs'));
- const legacySlug = /create-pool-with-(python|typescript)/;
- const remaining: string[] = [];
- for (const file of files) {
- if (legacySlug.test(await readFile(file, 'utf8'))) {
- remaining.push(path.relative(docs, file));
- }
- }
- assert.deepEqual(remaining, []);
-});
-
-test('legacy capacity URLs permanently redirect to the capacity page', async () => {
- const config = (await import('../next.config.mjs')).default;
- const redirects = (await config.redirects?.()) ?? [];
- for (const language of ['python', 'typescript']) {
- const source = `/how-to-guides/sandbox/create-pool-with-${language}`;
- assert.deepEqual(
- redirects.find((redirect) => redirect.source === source),
- { source, destination: '/fleets/guides/capacity-and-claims', permanent: true }
- );
- }
-});
diff --git a/docs/scripts/product-structure.test.ts b/docs/scripts/product-structure.test.ts
index db56b1dcbf..88da253626 100644
--- a/docs/scripts/product-structure.test.ts
+++ b/docs/scripts/product-structure.test.ts
@@ -15,7 +15,6 @@ const PRODUCTS: Array<[string, string]> = [
['cua-sdk', 'Cua SDK'],
['cua-driver', 'Cua Driver'],
['spaces', 'Cua Spaces'],
- ['fleets', 'Cua Fleets'],
['cua-bench', 'Cua Bench'],
['lume', 'Lume'],
['cua-cli', 'Cua CLI'],
diff --git a/docs/scripts/sandbox-navigation.test.ts b/docs/scripts/sandbox-navigation.test.ts
index 27074c824b..8a252fcf50 100644
--- a/docs/scripts/sandbox-navigation.test.ts
+++ b/docs/scripts/sandbox-navigation.test.ts
@@ -1,4 +1,4 @@
-// The Cua SDK and Cua Fleets trees: short task guides, local and cloud on the
+// The Cua SDK tree: short task guides, local and cloud on the
// same pages, and every removed slug redirected to the page that replaced it.
import assert from 'node:assert/strict';
import { access, readFile } from 'node:fs/promises';
@@ -74,8 +74,7 @@ test('entry pages link only to existing routes', async () => {
'cua-sdk/quickstart.mdx',
'cua-sdk/guides/cloud.mdx',
'cua-sdk/guides/local-runtimes.mdx',
- 'fleets/index.mdx',
- 'fleets/quickstart.mdx',
+ 'cua-sdk/guides/cua-cloud-ended.mdx',
]) {
const body = await readFile(path.join(content, page), 'utf8');
const urls = [...body.matchAll(/\[[^\]]+\]\((\/[^)]+)\)/g)].map((match) => match[1]);
@@ -95,9 +94,12 @@ test('removed Sandbox and Fleet pages redirect to the page that replaced them',
'cua-sdk/guides/set-up-fleet-credentials': 'cua-sdk/guides/cloud',
'cua-sdk/guides/examples/minecraft': 'cua-sdk/guides/agent-frameworks',
'cua-sdk/concepts/architecture': 'cua-sdk/concepts/how-sandboxes-work',
- 'fleets/concepts/pools-claims-and-guest-services': 'fleets',
- 'fleets/guides/claim-a-sandbox': 'fleets/guides/capacity-and-claims',
- 'fleets/guides/recover-first-cloud-fleet': 'fleets/guides/troubleshoot',
+ 'fleets': 'cua-sdk/guides/cua-cloud-ended',
+ 'fleets/concepts/pools-claims-and-guest-services': 'cua-sdk/guides/cua-cloud-ended',
+ 'fleets/guides/claim-a-sandbox': 'cua-sdk/guides/cua-cloud-ended',
+ 'fleets/guides/images': 'cua-sdk/guides/images',
+ 'fleets/guides/sidecars': 'cua-sdk/guides/sidecars',
+ 'fleets/guides/claim-secrets': 'cua-sdk/guides/secrets',
};
for (const [from, to] of Object.entries(expected)) {
assert.equal(redirects[from], to, from);
diff --git a/docs/scripts/tests/test_first_cloud_fleet_tutorial.py b/docs/scripts/tests/test_first_cloud_fleet_tutorial.py
deleted file mode 100644
index fb9bf7e5a7..0000000000
--- a/docs/scripts/tests/test_first_cloud_fleet_tutorial.py
+++ /dev/null
@@ -1,125 +0,0 @@
-"""Credential-free checks for the first Cloud Fleet tutorial and its Python example."""
-
-import asyncio
-import hashlib
-import importlib.metadata
-import inspect
-import os
-from pathlib import Path
-import sys
-import tempfile
-from types import ModuleType, SimpleNamespace
-import unittest
-from unittest.mock import AsyncMock, MagicMock, Mock
-
-
-DOCS = Path(__file__).resolve().parents[2]
-PAGE = DOCS / "content/docs/fleets/quickstart.mdx"
-RECOVERY = DOCS / "content/docs/fleets/guides/troubleshoot.mdx"
-PYTHON_SOURCE = DOCS / "public/scripts/first-cloud-fleet/first_cloud_fleet.py"
-TYPESCRIPT_SOURCE = DOCS / "public/scripts/first-cloud-fleet/first-cloud-fleet.ts.txt"
-IMAGE_REF = "registry.example/cua-image@sha256:" + "1" * 64
-SANDBOX_VERSION = "0.9.0"
-
-
-class PythonExampleTests(unittest.TestCase):
- def setUp(self):
- self.files = {}
- self.digest_override = None
- self.sandbox = SimpleNamespace(
- claim_name="cua-auto-test-claim",
- pool_name="cua-auto-test",
- files=SimpleNamespace(write_text=AsyncMock(side_effect=self.write_text)),
- shell=SimpleNamespace(run=AsyncMock(side_effect=self.run_command)),
- screenshot=AsyncMock(return_value=b"\x89PNG"),
- )
- self.context = MagicMock()
- self.context.__aenter__ = AsyncMock(return_value=self.sandbox)
- self.context.__aexit__ = AsyncMock(return_value=False)
- fake_sdk = ModuleType("cua_sandbox")
- fake_sdk.Image = SimpleNamespace(
- from_registry=Mock(side_effect=lambda value: value),
- linux=Mock(return_value="canonical-linux"),
- )
- fake_sdk.Sandbox = SimpleNamespace(ephemeral=Mock(return_value=self.context))
- self.fake_sdk = fake_sdk
- self.addCleanup(sys.modules.pop, "cua_sandbox", None)
- sys.modules["cua_sandbox"] = fake_sdk
- self.namespace = {"__name__": "tutorial_test"}
- exec(compile(PYTHON_SOURCE.read_text(), str(PYTHON_SOURCE), "exec"), self.namespace)
- cwd = os.getcwd()
- tmp = tempfile.TemporaryDirectory()
- self.addCleanup(tmp.cleanup)
- self.addCleanup(os.chdir, cwd)
- os.chdir(tmp.name)
-
- async def write_text(self, path, content):
- self.files[path] = content
-
- async def run_command(self, command):
- self.assertIn("sha256sum", command)
- source = self.files[self.namespace["SOURCE_PATH"]]
- digest = self.digest_override or hashlib.sha256(source.encode()).hexdigest()
- return SimpleNamespace(success=True, stdout=f"{digest} /tmp/x\n", stderr="")
-
- def test_success_uses_a_managed_ephemeral_sandbox(self):
- asyncio.run(self.namespace["run_tutorial"](IMAGE_REF))
- call = self.fake_sdk.Sandbox.ephemeral.call_args
- self.assertEqual(call.args, (IMAGE_REF,))
- self.assertIs(call.kwargs["local"], False)
- self.assertNotIn("pool", call.kwargs)
- self.sandbox.files.write_text.assert_awaited_once()
- self.sandbox.shell.run.assert_awaited_once()
- self.sandbox.screenshot.assert_awaited_once()
- self.context.__aexit__.assert_awaited_once()
-
- def test_default_image_is_the_canonical_linux_image(self):
- asyncio.run(self.namespace["run_tutorial"]())
- call = self.fake_sdk.Sandbox.ephemeral.call_args
- self.assertEqual(call.args, ("canonical-linux",))
- self.assertIs(call.kwargs["local"], False)
-
- def test_verification_failure_still_releases_the_claim(self):
- self.digest_override = "wrong-digest"
- with self.assertRaisesRegex(RuntimeError, "Verification failed"):
- asyncio.run(self.namespace["run_tutorial"](IMAGE_REF))
- self.context.__aexit__.assert_awaited_once()
-
-
-class DocumentationContractTests(unittest.TestCase):
- def test_python_example_matches_the_published_sdk(self):
- try:
- from cua_sandbox import Image, Sandbox
- except ImportError:
- self.skipTest("cua-sandbox is not installed")
- self.assertEqual(importlib.metadata.version("cua-sandbox"), SANDBOX_VERSION)
- inspect.signature(Sandbox.ephemeral).bind(
- Image.from_registry(IMAGE_REF), local=False, cpu=4, memory_mb=4096
- )
-
- def test_page_versions_match_the_scripts(self):
- page = PAGE.read_text()
- self.assertIn(f"cua-sandbox=={SANDBOX_VERSION}", page)
- self.assertIn(f'"cua-sandbox=={SANDBOX_VERSION}"', PYTHON_SOURCE.read_text())
- self.assertIn("from '@trycua/cua'", TYPESCRIPT_SOURCE.read_text())
- self.assertIn("@trycua/cua@", page)
- self.assertGreaterEqual(
- page.count("<Tabs groupId=\"language\" persist items={['CLI', 'Python', 'TypeScript']}>"), 1
- )
-
- def test_verification_is_independent_of_the_guest(self):
- self.assertIn("hashlib.sha256", PYTHON_SOURCE.read_text())
- self.assertIn("createHash('sha256')", TYPESCRIPT_SOURCE.read_text())
- self.assertIn("does not rely on the guest", PAGE.read_text())
-
- def test_cleanup_and_recovery_are_documented(self):
- page = PAGE.read_text()
- recovery = RECOVERY.read_text()
- self.assertIn("cua sb rm", page)
- self.assertIn("/fleets/guides/troubleshoot#clean-up-leftovers", page)
- self.assertIn("cua fleet pools gc", recovery)
- self.assertNotIn("—", page + recovery)
-
-
-if __name__ == "__main__":
- unittest.main()
diff --git a/docs/scripts/tests/test_fleet_docs_version_facts.py b/docs/scripts/tests/test_fleet_docs_version_facts.py
index 1255be06d8..de2f81b52d 100644
--- a/docs/scripts/tests/test_fleet_docs_version_facts.py
+++ b/docs/scripts/tests/test_fleet_docs_version_facts.py
@@ -41,7 +41,6 @@ EXPECTED_FACTS = {
"cua-sdk/concepts/how-sandboxes-work.mdx": (f"`cua-sandbox` {SANDBOX_VERSION}",),
"cua-sdk/guides/agent-frameworks.mdx": (f"cua-sandbox=={SANDBOX_VERSION}",),
"cua-sdk/guides/desktop.mdx": (f"'cua-sandbox[driver]=={SANDBOX_VERSION}'",),
- "fleets/guides/images.mdx": (f"`cua` {CUA_VERSION}",),
"cua-sdk/reference/index.mdx": (
f"`pip install cua` ({CUA_VERSION}",
f"`npm install @trycua/cua` ({TYPESCRIPT_CUA_VERSION}",
@@ -59,10 +58,6 @@ EXPECTED_FACTS = {
"cua-sdk/reference/typescript/index.mdx": (
f"`npm install @trycua/cua` ({TYPESCRIPT_CUA_VERSION})",
),
- "fleets/quickstart.mdx": (
- f"cua-sandbox=={SANDBOX_VERSION}",
- f"@trycua/cua@{TYPESCRIPT_CUA_VERSION}",
- ),
}
diff --git a/docs/scripts/tests/test_unified_sandbox_docs.py b/docs/scripts/tests/test_unified_sandbox_docs.py
index f9ce2113b8..fe32e97149 100644
--- a/docs/scripts/tests/test_unified_sandbox_docs.py
+++ b/docs/scripts/tests/test_unified_sandbox_docs.py
@@ -35,7 +35,7 @@ class UnifiedSandboxDocsTests(unittest.TestCase):
self.assertNotRegex(text, r"local=True[,)]", f"{slug} passes the default")
def test_pages_stay_short(self):
- for folder in ("cua-sdk", "fleets"):
+ for folder in ("cua-sdk",):
for path in (DOCS / folder).rglob("*.mdx"):
if "reference" in path.relative_to(DOCS).parts:
continue
@@ -54,12 +54,11 @@ class UnifiedSandboxDocsTests(unittest.TestCase):
self.assertIn('<span id="choose-a-published-fleet-image" />', text)
self.assertIn("Windows images do not include a Windows license", text)
- def test_cloud_page_points_to_fleets_for_dedicated_capacity(self):
+ def test_cloud_page_points_to_the_retirement_note(self):
text = page("cua-sdk/guides/cloud")
self.assertIn("local=False", text)
- self.assertIn("(/fleets)", text)
- meta = json.loads((DOCS / "fleets" / "meta.json").read_text())
- self.assertEqual(meta["title"], "Cua Fleets")
+ self.assertIn("(/cua-sdk/guides/cua-cloud-ended)", text)
+ self.assertFalse((DOCS / "fleets").exists())
if __name__ == "__main__":
diff --git a/libs/python/cua-sandbox/README.md b/libs/python/cua-sandbox/README.md
index 2f778ddab4..98ba415bfc 100644
--- a/libs/python/cua-sandbox/README.md
+++ b/libs/python/cua-sandbox/README.md
@@ -345,4 +345,4 @@ pool = await Pool.apply(
`Template.reconcile(CreateTemplateRequest(...))` remain for generated-schema
configuration.
-See [dedicated capacity](https://cua.ai/docs/fleets/guides/create-fleet-capacity).
+Cua Cloud (Fleets) ended on 16 October 2026; see [Cua Cloud (Fleets) has ended](https://cua.ai/docs/cua-sdk/guides/cua-cloud-ended).
diff --git a/scripts/docs-generators/config.json b/scripts/docs-generators/config.json
index 2b604d75fc..94f24d1572 100644
--- a/scripts/docs-generators/config.json
+++ b/scripts/docs-generators/config.json
@@ -725,103 +725,6 @@
"enabled": true,
"notes": "Renders the cua.env.v1 (cua-spacesd) and cua.daemon.v1 (cua daemon) contracts from a buf FileDescriptorSet (JSON, with SourceCodeInfo). gRPC-Web fallbacks, metadata keys and the protocol revision come from cua-proto's lib.rs. Needs buf on PATH (CI pins 1.73.0) or BUF=/path/to/buf."
},
- "fleet": {
- "name": "Cua Fleets (REST resources, SDK handle, Terraform)",
- "language": "rust",
- "sourcePath": "libs/cua/crates/cua-fleet",
- "docsOutputPath": "docs/content/docs/fleets/reference",
- "generatorScript": "scripts/docs-generators/fleet.ts",
- "watchPaths": [
- "libs/cua/crates/cua-fleet/**",
- "libs/cua/crates/cua-image/schema/**",
- "libs/cua/crates/cua-sdk/src/native/fleet.rs",
- "libs/cua/crates/cua-daemon/src/lib.rs",
- "libs/cua/VERSION",
- "libs/fleet/sdk/src/**",
- "libs/fleet/sdk-schema/src/**",
- "libs/fleet/backend/docs/swagger.json",
- "libs/fleet/terraform-provider-fleets/main.go",
- "libs/fleet/terraform-provider-fleets/docs/**",
- "libs/fleet/terraform-provider-fleets/internal/provider/**",
- "docs/content/docs/cua-sdk/reference/api/fleet.mdx",
- "docs/content/docs/fleets/guides/**",
- "scripts/docs-generators/fleet-descriptions.json",
- "scripts/docs-generators/fleet.test.ts",
- "scripts/docs-generators/lib/**"
- ],
- "buildCommand": "cargo run -q --locked -p cua-fleet --example fleet-docs-dump",
- "buildDirectory": "libs/cua",
- "extractionMethod": "source-and-dump",
- "outputs": [
- {
- "type": "reference",
- "outputFile": "index.mdx",
- "extractCommand": null
- },
- {
- "type": "reference",
- "outputFile": "pool.mdx",
- "extractCommand": null
- },
- {
- "type": "reference",
- "outputFile": "template.mdx",
- "extractCommand": null
- },
- {
- "type": "reference",
- "outputFile": "claim.mdx",
- "extractCommand": null
- },
- {
- "type": "reference",
- "outputFile": "sandbox.mdx",
- "extractCommand": null
- },
- {
- "type": "reference",
- "outputFile": "secret.mdx",
- "extractCommand": null
- },
- {
- "type": "reference",
- "outputFile": "service-url.mdx",
- "extractCommand": null
- },
- {
- "type": "reference",
- "outputFile": "image.mdx",
- "extractCommand": null
- },
- {
- "type": "reference",
- "outputFile": "namespace.mdx",
- "extractCommand": null
- },
- {
- "type": "reference",
- "outputFile": "api-key.mdx",
- "extractCommand": null
- },
- {
- "type": "reference",
- "outputFile": "terraform.mdx",
- "extractCommand": null
- },
- {
- "type": "reference",
- "outputFile": "errors.mdx",
- "extractCommand": null
- },
- {
- "type": "nav",
- "outputFile": "meta.json",
- "extractCommand": null
- }
- ],
- "enabled": true,
- "notes": "No OpenAPI covers the Fleet resources (Kubernetes custom resources behind the gateway's /api/k8s proxy), so each fact comes from the nearest authoritative artifact: object fields from the osgym.cua.ai CRDs (cyclops-sdk-schema, via the cua-fleet fleet-docs-dump example) and cua-image's checked-in Image schema; REST routes, methods and statuses from the Fleet Rust client (libs/fleet/sdk/src); other endpoints and error responses from the gateway swagger; SDK rows from the UniFFI Fleet handle, linked to the Cua SDK reference; Terraform from the provider's generated schema, CRD mapping and registry docs; the Terraform example from the tested guide block main-tf. fleet-descriptions.json holds public descriptions for fields whose read-only source text describes Fleet internals. FLEET_DOCS_DUMP=<file> skips the cargo build."
- },
"spaces": {
"name": "Cua Spaces (MCP contract)",
"language": "rust",
diff --git a/scripts/docs-generators/fleet-descriptions.json b/scripts/docs-generators/fleet-descriptions.json
deleted file mode 100644
index 03ce36756b..0000000000
--- a/scripts/docs-generators/fleet-descriptions.json
+++ /dev/null
@@ -1,92 +0,0 @@
-{
- "_comment": "Public descriptions for Fleet reference fields whose source text is missing or describes Fleet internals. The sources are the read-only libs/fleet mirror (CRD doc comments in sdk-schema, swag annotations in backend), so they cannot be edited here; fix them upstream in trycua/cloud and delete the entry. fleet.ts fails when a key no longer names a field.",
- "crd": {
- "OSGymSandboxWarmPool": {
- "spec.autoscaling": "Claim-driven autoscaling. When set, Fleet sizes the pool from its live claims (Pending and Bound) and owns `spec.replicas`: a Pending claim grows the pool, deleting claims shrinks it. Absent: `spec.replicas` is a static size.",
- "spec.autoscaling.initialPoolSize": "Warm head start: `spec.replicas` starts here when the pool is created, so the first claims bind without a cold start. It then follows claim demand, never below `minPoolSize`.",
- "spec.autoscaling.maxPoolSize": "Most sandboxes the pool scales to.",
- "spec.autoscaling.minPoolSize": "Fewest warm sandboxes kept while autoscaling. `0` lets the pool scale to zero when there are no claims.",
- "spec.replicas": "Warm sandboxes to keep ready. With `autoscaling`, Fleet sets it.",
- "spec.sandboxTemplateRef": "The template the pool's sandboxes run.",
- "status.replicas": "Sandboxes the pool currently owns.",
- "status.readyReplicas": "Sandboxes ready to be claimed."
- },
- "OSGymSandboxClaim": {
- "spec.bindDeadline": "Seconds the claim may stay Pending before it is marked Failed (Fleet's default and the SDK's value: 900). A Pending claim is what grows an autoscaled pool, so leave room for a cold boot.",
- "spec.lifecycle": "When the claim expires and what happens to its sandbox.",
- "spec.lifecycle.autoRenew": "Set by Fleet on claims it renews itself. Leave it `false`.",
- "spec.lifecycle.shutdownPolicy": "`Retain`: when the claim is deleted, the sandbox returns to the pool and restarts clean. `Delete`: the sandbox is destroyed and the pool creates a new one.",
- "spec.lifecycle.shutdownTime": "Absolute UTC expiry (RFC 3339). Fleet deletes the claim, and releases its sandbox, once it passes. Renew by patching it forward.",
- "spec.sandboxTemplateRef": "The template of the pool to claim from.",
- "spec.warmpool": "Where to take a sandbox from: `default` (the pool running the template), `none`, or a pool name.",
- "status.conditions": "Kubernetes conditions of the claim.",
- "status.conditions[].lastTransitionTime": "When the condition last changed (RFC 3339).",
- "status.conditions[].message": "Human-readable detail.",
- "status.conditions[].reason": "Machine-readable reason.",
- "status.conditions[].status": "`True`, `False` or `Unknown`.",
- "status.conditions[].type": "Condition type.",
- "status.phase": "`Pending`, `Bound` or `Failed`.",
- "status.sandbox": "The bound sandbox.",
- "status.sandbox.name": "Name of the bound sandbox.",
- "status.sandbox.service": "In-cluster DNS name of the sandbox's Service."
- },
- "OSGymSandboxTemplate": {
- "spec.vmTemplate": "What each sandbox runs.",
- "spec.vmTemplate.command": "`gvisor` and `macos` only: entrypoint of the sandbox container, overriding the image's.",
- "spec.vmTemplate.containerDiskImage": "The image: a containerDisk for `kubevirt`, a container image for `gvisor` and `macos`.",
- "spec.vmTemplate.cpuCores": "Virtual CPUs per sandbox.",
- "spec.vmTemplate.firmware": "VM firmware for `kubevirt`: `efi` for UEFI-only images such as Windows, `bios` for the Linux images.",
- "spec.vmTemplate.imagePullPolicy": "`gvisor` and `macos` only: when to pull the image (default `IfNotPresent`).",
- "spec.vmTemplate.imagePullSecret": "Secret in the pool's namespace with registry credentials for a private image. Omit it for a public image.",
- "spec.vmTemplate.memory": "Memory per sandbox, as a Kubernetes quantity such as `8Gi`.",
- "spec.vmTemplate.nestedVirtualization": "Expose hardware virtualization (KVM) inside the VM.",
- "spec.vmTemplate.nodeSelector": "`gvisor` and `macos` only: node selector of the sandbox pod. Fleet's default fits the runtime.",
- "spec.vmTemplate.oidc": "Workload identity: Fleet puts an OIDC access token for your account at `/var/run/cua/oidc/token` in the guest and keeps it fresh, so the workload can federate into AWS (`sts:AssumeRoleWithWebIdentity`) or any other provider that trusts the token.",
- "spec.vmTemplate.oidc.awsRegion": "AWS region for AWS SDK calls in the guest.",
- "spec.vmTemplate.oidc.awsRoleArn": "When set, the guest's AWS SDK assumes this role with the token (environment and `~/.aws/config` are set up).",
- "spec.vmTemplate.oidc.credentialsSecret": "Secret in the pool's namespace holding the client credentials (`client_id`, `client_secret`) that mint the token.",
- "spec.vmTemplate.oidc.refreshIntervalSeconds": "How often the guest refreshes the token (half its one-hour lifetime by default).",
- "spec.vmTemplate.oidc.tokenUrl": "Token endpoint that mints the workload token.",
- "spec.vmTemplate.probes": "Kubernetes `readinessProbe` and `livenessProbe` for the VM, so a sandbox counts as ready only when the guest serves.",
- "spec.vmTemplate.runtime": "`kubevirt`: each sandbox is a VM booted from `containerDiskImage`. `gvisor`: a gVisor container of the image. `macos`: a macOS sandbox. For `gvisor` and `macos`, `firmware`, `cpuCores` and `memory` are advisory.",
- "spec.vmTemplate.runtimeClassName": "`gvisor` and `macos` only: RuntimeClass of the sandbox pod. Fleet's default fits the runtime.",
- "spec.vmTemplate.services": "Ports each sandbox publishes, as a Service named `<sandbox>-<name>`. Reach them through service URLs.",
- "spec.vmTemplate.services[].protocol": "`TCP` or `UDP`.",
- "spec.vmTemplate.services[].targetPort": "Port in the sandbox.",
- "spec.vmTemplate.tolerations": "`gvisor` and `macos` only: tolerations of the sandbox pod. Fleet's default fits the runtime."
- },
- "OSGymSandbox": {
- "status.phase": "`Pending`, `Ready` or `Terminating`.",
- "status.ready": "Whether the sandbox is ready.",
- "status.resetIssuedAt": "When Fleet began restarting the sandbox to return it to its pool.",
- "status.resetVmiUid": "Identifies the VM instance that restart replaces.",
- "status.runtime": "Runtime that provisioned the sandbox: `macos`, `gvisor`, or empty for `kubevirt`.",
- "status.service": "In-cluster DNS name of the sandbox's Service.",
- "status.vmName": "Name of the sandbox's VM (`kubevirt`)."
- }
- },
- "swagger": {
- "handlers.CreateSignedServiceURLRequest": {
- "claim": "The claim that holds the sandbox.",
- "expiresInSeconds": "Lifetime of the URL, in seconds.",
- "label": "A label for the URL, at most 120 UTF-8 bytes.",
- "logicalService": "The service as the template names it, for example `env`.",
- "sandbox": "The sandbox name (`status.sandbox.name` of the claim).",
- "service": "The sandbox's Service: `<sandbox>-<logicalService>`."
- },
- "handlers.CreateNamespaceRequest": {
- "name": "Namespace name: a DNS label."
- },
- "handlers.CreateUserKeyRequest": {
- "name": "A name for the key.",
- "scope": "Namespaces the key is limited to."
- },
- "handlers.CreateUserKeyResponse": {
- "client_id": "OAuth client ID.",
- "client_secret": "OAuth client secret. Returned once; it cannot be read again.",
- "name": "The key's name.",
- "scope": "Namespaces the key is limited to.",
- "token_url": "Token endpoint for the client-credentials grant."
- }
- }
-}
diff --git a/scripts/docs-generators/fleet.test.ts b/scripts/docs-generators/fleet.test.ts
deleted file mode 100644
index dc0627e179..0000000000
--- a/scripts/docs-generators/fleet.test.ts
+++ /dev/null
@@ -1,178 +0,0 @@
-import assert from 'node:assert/strict';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import test from 'node:test';
-import {
- DESCRIPTIONS_FILE,
- OBJECTS,
- SOURCES,
- applyOverrides,
- daemonMapping,
- messageTemplate,
- neutralType,
- notFoundVariants,
- parseClientOps,
- parseHandle,
- parseRoutes,
- parseTfDocs,
- parseTfSchema,
-} from './fleet';
-import { enumVariants, firstSentence, structFields } from './lib/rust-source';
-import { cleanDescription, fieldTable, flattenSchema, typeOf, type Schema } from './lib/schema-fields';
-
-const read = (p: string) => fs.readFileSync(p, 'utf-8');
-
-test('routes evaluate to path templates', () => {
- const routes = parseRoutes(`
-const PREFIX: &str = "api/k8s/apis/x/v1/namespaces/";
-const KEYS: &str = "api/user-keys";
-pub fn pool_item(base: &Url, namespace: &str, name: &str) -> Result<Url, SdkError> {
- route(base, format!("{PREFIX}{namespace}/pools/{name}"))
-}
-pub fn key_collection(base: &Url) -> Result<Url, SdkError> {
- route(base, KEYS.into())
-}
-pub fn key_item(base: &Url, id: &str) -> Result<Url, SdkError> {
- let mut url = key_collection(base)?;
- url.path_segments_mut().unwrap().push(id);
- Ok(url)
-}
-`);
- assert.equal(routes.get('pool_item'), '/api/k8s/apis/x/v1/namespaces/{namespace}/pools/{name}');
- assert.equal(routes.get('key_item'), '/api/user-keys/{id}');
-});
-
-test('every REST operation the objects name resolves in the Fleet client', () => {
- const routes = parseRoutes(read(path.join(SOURCES.sdkDir, 'routes.rs')));
- const ops = parseClientOps(SOURCES.sdkDir, routes);
- const pool = ops.get('create_pool');
- assert.equal(pool?.method, 'POST');
- // The request goes to the collection even though the item route is validated first.
- assert.match(pool!.path, /\/osgymsandboxwarmpools$/);
- assert.deepEqual(pool!.calls.sort(), ['create_namespace_if_missing', 'delete_namespace']);
- assert.equal(ops.get('renew_claim')?.method, 'PATCH');
- assert.deepEqual(ops.get('delete_claim')?.statuses, [200, 202, 204, 404]);
- for (const def of OBJECTS)
- for (const ref of def.rest)
- if ('client' in ref) assert.ok(ops.has(ref.client), `${def.slug}: ${ref.client}`);
-});
-
-test('every SDK method the objects name exists on the UniFFI handle', () => {
- const handle = parseHandle(read(SOURCES.handle), new Map());
- for (const def of OBJECTS) for (const key of def.sdk) assert.ok(handle.has(key), `${def.slug}: ${key}`);
- assert.deepEqual(handle.get('Fleet.release')?.params, ['namespace', 'name']);
-});
-
-test('the Terraform schema parses from the generated provider source', () => {
- const dir = path.join(SOURCES.tfDir, 'internal', 'provider');
- const tf = parseTfSchema(read(path.join(dir, 'pool_generated.go')), 'poolResourceSchema');
- const name = tf.attrs.find((a) => a.name === 'name')!;
- assert.ok(name.required && name.requiresReplace);
- assert.deepEqual(name.length, [1, 63]);
- assert.ok(name.pattern?.startsWith('^[a-z0-9]'));
- assert.deepEqual(tf.attrs.find((a) => a.name === 'runtime')?.oneOf, ['gvisor', 'kubevirt', 'macos']);
- assert.deepEqual(
- tf.blocks.map((b) => [b.name, b.nesting]),
- [
- ['service', 'set'],
- ['autoscaling', 'single'],
- ]
- );
- const docs = parseTfDocs(read(path.join(SOURCES.tfDir, 'docs', 'resources', 'pool.md')));
- assert.ok(docs.args.get('liveness_probe_json'));
- assert.match(docs.importCode ?? '', /terraform import fleets_pool\./);
-});
-
-test('errors: variants, messages and their SDK cases', () => {
- const variants = enumVariants(
- `pub enum E {
- /// Bad input.
- #[error("invalid argument: {0}")]
- Invalid(String),
- #[error(transparent)]
- Sdk(#[from] X),
- /// Timed out.
- #[error("sandbox {sandbox} has no {service:?}")]
- Missing {
- sandbox: String,
- service: String,
- },
-}`,
- 'E'
- );
- assert.deepEqual(
- variants.map((v) => [v.name, v.message]),
- [
- ['Invalid', 'invalid argument: {0}'],
- ['Sdk', 'transparent'],
- ['Missing', 'sandbox {sandbox} has no {service:?}'],
- ]
- );
- assert.equal(messageTemplate('sandbox {sandbox} has no {service:?}: {}'), 'sandbox <sandbox> has no <service>: <detail>');
- const daemon = daemonMapping(read(SOURCES.daemonLib));
- assert.equal(daemon.map.get('MissingCredentials'), 'ProviderNotConfigured');
- assert.ok(daemon.guest.includes('SpacesdNotAvailable'));
- assert.deepEqual([...notFoundVariants(read(SOURCES.fleetLib))].sort(), ['Sdk', 'UnknownService']);
-});
-
-test('schema fields flatten with types, defaults and constraints', () => {
- const schema: Schema = {
- type: 'object',
- required: ['spec'],
- properties: {
- spec: {
- type: 'object',
- required: ['replicas'],
- properties: {
- replicas: { type: 'integer', minimum: 0, description: 'Warm\nsandboxes.' },
- runtime: { type: 'string', enum: ['kubevirt', 'gvisor'], default: 'kubevirt' },
- services: { type: 'array', items: { type: 'object', properties: { port: { type: 'integer' } } } },
- },
- },
- },
- };
- const fields = flattenSchema(schema);
- assert.deepEqual(
- fields.map((f) => [f.path, f.type, f.required]),
- [
- ['spec', 'object', true],
- ['spec.replicas', 'integer', true],
- ['spec.runtime', '"kubevirt" | "gvisor"', false],
- ['spec.services', 'object[]', false],
- ['spec.services[].port', 'integer', false],
- ]
- );
- const table = fieldTable(fields).join('\n');
- assert.match(table, /\| `spec.replicas` \| `integer` \| required \| Warm sandboxes\. At least 0\. \|/);
- assert.match(table, /\| `spec.runtime` \| `"kubevirt" \\\| "gvisor"` \| `"kubevirt"` \|/);
- assert.equal(typeOf({ type: 'object', additionalProperties: { type: 'string' } }), 'map of string');
- assert.equal(
- cleanDescription('Grows the pool.\nSee docs/decisions/2026-06-15-x.md. Done (trycua/cloud#7887).'),
- 'Grows the pool. Done.'
- );
-});
-
-test('description overrides must name existing fields', () => {
- const fields = [{ path: 'spec.a', description: 'internal' }];
- assert.equal(applyOverrides(fields, { 'spec.a': 'public' }, 'X')[0].description, 'public');
- assert.throws(() => applyOverrides(fields, { 'spec.b': 'x' }, 'X'), /has no field spec\.b/);
- const file = JSON.parse(read(DESCRIPTIONS_FILE));
- assert.ok(file.crd.OSGymSandboxClaim['spec.lifecycle.autoRenew']);
-});
-
-test('small helpers', () => {
- assert.equal(firstSentence('Deletes pools idle (default 0, i.e. now). More.'), 'Deletes pools idle (default 0, i.e. now).');
- assert.equal(neutralType('Vec<FleetPool>'), '`FleetPool[]`');
- assert.equal(neutralType('()'), 'none');
- assert.deepEqual(
- structFields(
- `#[serde(rename_all = "camelCase")]
-pub struct R {
- pub size_bytes: u64,
- pub name: String,
-}`,
- 'R'
- ).map((f) => f.name),
- ['sizeBytes', 'name']
- );
-});
diff --git a/scripts/docs-generators/fleet.ts b/scripts/docs-generators/fleet.ts
deleted file mode 100644
index a5c952fea5..0000000000
--- a/scripts/docs-generators/fleet.ts
+++ /dev/null
@@ -1,1501 +0,0 @@
-#!/usr/bin/env npx tsx
-
-/**
- * Cua Fleets reference generator: docs/content/docs/fleets/reference/.
- *
- * There is no OpenAPI document for the Fleet resources (they are Kubernetes
- * custom resources behind the gateway's `/api/k8s` proxy), so each fact comes
- * from the nearest authoritative artifact:
- *
- * - object fields: the `osgym.cua.ai` CRDs as `cyclops-sdk-schema` renders
- * them, plus the SDK's extension fields, secrets and example bodies, all
- * printed by `cargo run -p cua-fleet --example fleet-docs-dump`; the Image
- * resource from `cua-image`'s checked-in JSON Schema;
- * - REST operations on custom resources: the Fleet Rust client
- * (`libs/fleet/sdk/src`): its route builders, HTTP methods and accepted
- * statuses; the other endpoints and every error response: the gateway's
- * swagger (`libs/fleet/backend/docs/swagger.json`);
- * - SDK: the UniFFI `Fleet` handle (`cua-sdk/src/native/fleet.rs`), linked to
- * the Cua SDK reference instead of repeating signatures;
- * - Terraform: the provider's generated schema (`pool_generated.go`,
- * `provider.go`), its CRD mapping and its registry docs;
- * - errors: `cua_fleet::Error`, the Fleet client's `SdkError`, and the SDK
- * error each one surfaces as (`cua-daemon`).
- *
- * Every curated list below (which operations belong to which object) is
- * checked against those sources, so a renamed method or route fails here.
- *
- * Usage:
- * pnpm --dir docs docs:generate:fleet
- * pnpm --dir docs docs:check:fleet
- *
- * FLEET_DOCS_DUMP=<file> skips the cargo build and reads that dump instead.
- */
-
-import { execFileSync } from 'child_process';
-import * as fs from 'fs';
-import * as path from 'path';
-import {
- DOCS_CONTENT,
- REPO_ROOT,
- codeCell,
- codeFence,
- escapeMdxText,
- escapeTableCell,
- finish,
- isCheckMode,
- metaJson,
- renderPage,
- slug,
- syncFiles,
-} from './lib/mdx';
-import {
- enumVariants,
- firstSentence,
- flattenRustdocLinks,
- implFns,
- jsonTypeOfRust,
- matchBrace,
- structFields,
-} from './lib/rust-source';
-import { type Schema, cleanDescription, fieldTable, flattenSchema, taggedVariants, typeOf } from './lib/schema-fields';
-
-const OUT_DIR = path.join(DOCS_CONTENT, 'fleets', 'reference');
-const REGENERATE = 'pnpm --dir docs docs:generate:fleet';
-const R = (...p: string[]) => path.join(REPO_ROOT, ...p);
-
-export const SOURCES = {
- sdkDir: R('libs', 'fleet', 'sdk', 'src'),
- swagger: R('libs', 'fleet', 'backend', 'docs', 'swagger.json'),
- tfDir: R('libs', 'fleet', 'terraform-provider-fleets'),
- handle: R('libs', 'cua', 'crates', 'cua-sdk', 'src', 'native', 'fleet.rs'),
- fleetLib: R('libs', 'cua', 'crates', 'cua-fleet', 'src', 'lib.rs'),
- claimSecrets: R('libs', 'cua', 'crates', 'cua-fleet', 'src', 'claim_secrets.rs'),
- daemonLib: R('libs', 'cua', 'crates', 'cua-daemon', 'src', 'lib.rs'),
- imageSchema: R('libs', 'cua', 'crates', 'cua-image', 'schema', 'image-v1alpha1.schema.json'),
- sdkReference: R('docs', 'content', 'docs', 'cua-sdk', 'reference'),
- fleetDocs: R('docs', 'content', 'docs', 'fleets'),
-};
-
-// ------------------------------------------------------------------ inputs
-
-export interface Crd {
- metadata: { name: string };
- spec: {
- group: string;
- names: { kind: string; plural: string; shortNames?: string[] };
- versions: Array<{ name: string; schema: { openAPIV3Schema: Schema } }>;
- };
-}
-
-export interface Extension {
- object: string;
- field: string;
- type: string;
- description: string;
-}
-
-export interface FleetDump {
- crds: Crd[];
- config: {
- default_base_url: string;
- default_token_url: string;
- missing_credentials: string;
- default_claim_bind_deadline_seconds: number;
- remote_builds_supported: boolean;
- };
- extensions: Extension[];
- examples: { pool: unknown; template: unknown; claim: unknown };
- secrets: {
- claim: { prefix: string; key: string; label: string; wait_seconds: number; example: unknown };
- registry: { prefix: string; max_sidecars: number; example: unknown };
- };
-}
-
-function loadDump(): FleetDump {
- const file = process.env.FLEET_DOCS_DUMP;
- if (file) return JSON.parse(fs.readFileSync(file, 'utf-8'));
- const out = execFileSync(
- process.env.CARGO || 'cargo',
- ['run', '-q', '--locked', '-p', 'cua-fleet', '--example', 'fleet-docs-dump'],
- { cwd: R('libs', 'cua'), encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'inherit'] }
- );
- return JSON.parse(out);
-}
-
-const read = (p: string) => fs.readFileSync(p, 'utf-8');
-
-export const DESCRIPTIONS_FILE = path.join(__dirname, 'fleet-descriptions.json');
-
-export interface Descriptions {
- crd: Record<string, Record<string, string>>;
- swagger: Record<string, Record<string, string>>;
-}
-
-/** Applies `overrides` (path -> text) to `fields`; throws on a path that names no field. */
-export function applyOverrides<T extends { path: string; description: string }>(
- fields: T[],
- overrides: Record<string, string>,
- where: string,
- strict = true
-): T[] {
- const known = new Set(fields.map((f) => f.path));
- if (strict)
- for (const key of Object.keys(overrides))
- if (!known.has(key)) throw new Error(`fleet-descriptions.json: ${where} has no field ${key}`);
- return fields.map((f) => (overrides[f.path] ? { ...f, description: overrides[f.path] } : f));
-}
-
-// ------------------------------------------------------- REST: Fleet client
-
-export interface RouteTemplate {
- fn: string;
- path: string;
-}
-
-/** Route builders in `routes.rs`, evaluated to path templates (`/api/.../{namespace}/...`). */
-export function parseRoutes(src: string): Map<string, string> {
- const consts = new Map<string, string>();
- for (const m of src.matchAll(/const (\w+): &str = "([^"]*)";/g)) consts.set(m[1], m[2]);
- const fns = new Map<string, string>();
- const bodies = new Map<string, string>();
- for (const m of src.matchAll(/\npub fn (\w+)\(([^)]*)\) -> Result<Url, SdkError> \{/g)) {
- const open = (m.index ?? 0) + m[0].length - 1;
- bodies.set(m[1], src.slice(open, matchBrace(src, open) + 1));
- }
- const evalFn = (name: string, depth = 0): string => {
- if (fns.has(name)) return fns.get(name)!;
- if (depth > 4) throw new Error(`route ${name} recursion`);
- const body = bodies.get(name);
- if (!body) throw new Error(`route ${name} not found in routes.rs`);
- let p: string | null = null;
- const fmt = /route\(\s*base,\s*format!\(\s*"([^"]*)"/.exec(body);
- const constRoute = /route\(\s*base,\s*(\w+)\.into\(\)\s*\)/.exec(body);
- const inner = /(?:let (?:mut )?url = |^\s*)(\w+)\(base(?:,[^)]*)?\)\?/m.exec(body);
- if (fmt) {
- p = `/${fmt[1].replace(/\{([A-Z_]+)\}/g, (_, c: string) => {
- if (!consts.has(c)) throw new Error(`route ${name}: unknown const ${c}`);
- return consts.get(c)!;
- })}`;
- } else if (constRoute) {
- p = `/${consts.get(constRoute[1])}`;
- } else if (inner && bodies.has(inner[1])) {
- p = evalFn(inner[1], depth + 1);
- const q = /append_pair\("(\w+)",\s*(\w+)\)/.exec(body);
- if (q) p += `?${q[1]}={${q[2]}}`;
- const push = /\.push\((\w+)\)/.exec(body);
- if (push) p += `/{${push[1]}}`;
- const scheme = /"https" => "wss"/.test(body);
- if (scheme) p = `wss:${p}`;
- }
- if (!p) throw new Error(`route ${name}: unrecognized body`);
- p = p.replace(/\{service_name\}\{path\}/, '{service}{path}');
- fns.set(name, p);
- return p;
- };
- for (const name of bodies.keys()) evalFn(name);
- return fns;
-}
-
-export interface ClientOp {
- /** Client method (`create_pool`). */
- fn: string;
- /** The operation name the client reports in errors (`create pool`). */
- op: string;
- method: string;
- path: string;
- statuses: number[];
- /** Other client calls the method makes first or after. */
- calls: string[];
- doc: string;
-}
-
-/** Operations of the Fleet Rust client, keyed by method name. */
-export function parseClientOps(dir: string, routes: Map<string, string>): Map<string, ClientOp> {
- const ops = new Map<string, ClientOp>();
- for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.rs')).sort()) {
- const src = read(path.join(dir, file));
- const helpers = new Map<string, string>();
- for (const h of src.matchAll(/fn (\w+_url)\(&self[^)]*\)[^{]*\{/g)) {
- const open = (h.index ?? 0) + h[0].length - 1;
- helpers.set(h[1], src.slice(open, matchBrace(src, open) + 1));
- }
- for (const f of implFns(src, 'CyclopsClient')) {
- const op = /send_(?:json|unit)(?:_crud)?\(\s*(?:self\.as_ref\(\),\s*)?"([^"]+)"/.exec(f.body);
- if (!op) continue;
- const method = /merge_patch_request\(/.test(f.body)
- ? 'PATCH'
- : /json_request\(\s*"(\w+)"/.exec(f.body)?.[1];
- if (!method) throw new Error(`${file}: ${f.name}: no HTTP method`);
- const routeFn = requestRoute(f.body, routes, helpers);
- if (!routeFn) throw new Error(`${file}: ${f.name}: no route`);
- const statuses = /&\[([\d,\s]+)\]/.exec(f.body)?.[1].split(',').map((s) => Number(s.trim())) ?? [];
- const calls = [...f.body.matchAll(/(?:self\)?\s*\.\s*|Arc::clone\(&self\)\s*\.\s*)(create_namespace_if_missing|delete_namespace)\(/g)].map(
- (m) => m[1]
- );
- ops.set(f.name, { fn: f.name, op: op[1], method, path: routes.get(routeFn)!, statuses, calls, doc: f.doc });
- }
- }
- return ops;
-}
-
-/**
- * The route the request goes to: the URL argument of `json_request(..)` or
- * `merge_patch_request(..)`, resolved through its `let` binding or a
- * `self.x_url(..)` helper. Other route calls in the body only validate names.
- */
-function requestRoute(body: string, routes: Map<string, string>, helpers: Map<string, string>): string | undefined {
- const arg = /(?:json_request\(\s*"\w+",|merge_patch_request\()\s*(routes::\w+\(|\w+\()?(\w+)?/.exec(body);
- if (!arg) return undefined;
- if (arg[1]) {
- const name = arg[1].replace(/^routes::/, '').replace(/\($/, '');
- return routes.has(name) ? name : undefined;
- }
- const v = arg[2];
- const binding = new RegExp(`let (?:mut )?${v}(?::[^=]+)?\\s*=\\s*([^;]+);`).exec(body);
- if (!binding) {
- // `routes::claim_collection(base, ns).and_then(|url| Ok(json_request("POST", url, ..)))`:
- // the URL is the closure argument of the route builder's `and_then`.
- const chained = new RegExp(`(?:routes::)?\\b(\\w+)\\([^;]*?\\)\\s*\\.and_then\\(\\|${v}\\|`).exec(body);
- return chained && routes.has(chained[1]) ? chained[1] : undefined;
- }
- const direct = /(?:routes::)?\b(\w+)\(/.exec(binding[1]);
- if (direct && routes.has(direct[1])) return direct[1];
- const helper = /self\.(\w+_url)\(/.exec(binding[1]);
- if (helper && helpers.has(helper[1])) return routeOf(helpers.get(helper[1])!, routes);
- return undefined;
-}
-
-function routeOf(body: string, routes: Map<string, string>): string | undefined {
- // The last route builder the method calls is the one it sends to
- // (earlier calls validate names).
- const names = [...body.matchAll(/(?:routes::)?\b(\w+)\(\s*(?:self\.)?base_url\(\)/g)].map((m) => m[1]);
- return names.filter((n) => routes.has(n)).pop();
-}
-
-
-// ------------------------------------------------------------ REST: swagger
-
-export interface SwaggerParam {
- name: string;
- in: string;
- type?: string;
- description?: string;
- required?: boolean;
- schema?: { $ref?: string };
-}
-
-export interface SwaggerOp {
- summary: string;
- description?: string;
- parameters?: SwaggerParam[];
- responses: Record<string, { description: string; schema?: Schema & { $ref?: string } }>;
- tags: string[];
-}
-
-export interface Swagger {
- paths: Record<string, Record<string, SwaggerOp>>;
- definitions: Record<string, Schema>;
- securityDefinitions: Record<string, { name: string; in: string }>;
-}
-
-// ------------------------------------------------------------- SDK handle
-
-export interface HandleMethod {
- owner: string;
- name: string;
- summary: string;
- params: string[];
- returns: string;
- isAsync: boolean;
- /** Link into the Cua SDK reference, when that page documents the method. */
- href?: string;
-}
-
-export function parseHandle(src: string, sdkAnchors: Map<string, string>): Map<string, HandleMethod> {
- const out = new Map<string, HandleMethod>();
- for (const owner of ['Fleet', 'FleetPools']) {
- for (const f of implFns(src, owner)) {
- const key = `${owner}.${f.name}`;
- out.set(key, {
- owner,
- name: f.name,
- summary: firstSentence(f.doc),
- params: f.params.map((p) => p.name),
- returns: unwrapResult(f.returns),
- isAsync: f.isAsync,
- href: sdkAnchors.get(key),
- });
- }
- }
- return out;
-}
-
-function unwrapResult(t: string): string {
- const m = /^Result<(.+)>$/.exec(t.replace(/\s+/g, ' ').trim());
- const inner = m ? m[1] : t;
- return inner.replace(/^Arc<(.+)>$/, '$1');
-}
-
-/** `Fleet.acquire` -> `/cua-sdk/reference/.../page#fleetacquire`, from the generated SDK pages. */
-export function sdkAnchors(dir: string): Map<string, string> {
- const out = new Map<string, string>();
- if (!fs.existsSync(dir)) return out;
- const walk = (d: string) => {
- for (const e of fs.readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
- const p = path.join(d, e.name);
- if (e.isDirectory()) walk(p);
- else if (e.name.endsWith('.mdx')) {
- const rel = path.relative(DOCS_CONTENT, p).replace(/\\/g, '/').replace(/\.mdx$/, '').replace(/\/index$/, '');
- for (const m of read(p).matchAll(/^#{2,4} `?((?:Fleet|FleetPools)\.\w+)`?\s*$/gm)) {
- if (!out.has(m[1])) out.set(m[1], `/${rel}#${slug(m[1])}`);
- }
- }
- }
- };
- walk(dir);
- return out;
-}
-
-// -------------------------------------------------------------- Terraform
-
-export interface TfAttr {
- name: string;
- kind: 'String' | 'Int64' | 'Bool' | 'List';
- /** Element kind of a `List` attribute. */
- element?: 'String' | 'Int64' | 'Bool';
- required: boolean;
- optional: boolean;
- computed: boolean;
- sensitive: boolean;
- description: string;
- oneOf?: string[];
- atLeast?: number;
- between?: [number, number];
- length?: [number, number];
- pattern?: string;
- requiresReplace: boolean;
- json: boolean;
-}
-
-export interface TfBlock {
- name: string;
- nesting: 'set' | 'single';
- attrs: TfAttr[];
-}
-
-export interface TfSchema {
- description: string;
- attrs: TfAttr[];
- blocks: TfBlock[];
-}
-
-function goString(lit: string): string {
- return JSON.parse(lit);
-}
-
-/** The entries of a Go `map[string]...{ "k": v, ... }` literal starting at its `{`. */
-function goMapEntries(src: string, open: number): Array<[string, string]> {
- const close = matchBrace(src, open);
- const body = src.slice(open + 1, close);
- const out: Array<[string, string]> = [];
- let i = 0;
- while (i < body.length) {
- const k = /\s*"([^"]+)":\s*/y;
- k.lastIndex = i;
- const m = k.exec(body);
- if (!m) break;
- let j = k.lastIndex;
- const start = j;
- // value ends at the top-level comma
- let depth = 0;
- for (; j < body.length; j += 1) {
- const c = body[j];
- if (c === '"') {
- for (j += 1; body[j] !== '"'; j += 1) if (body[j] === '\\') j += 1;
- } else if ('{(['.includes(c)) depth += 1;
- else if ('})]'.includes(c)) depth -= 1;
- else if (c === ',' && depth === 0) break;
- }
- out.push([m[1], body.slice(start, j).trim()]);
- i = j + 1;
- }
- return out;
-}
-
-function tfAttr(name: string, v: string, regexes: Map<string, string>): TfAttr {
- const kind = /^schema\.(String|Int64|Bool|List)Attribute\{/.exec(v)?.[1] as TfAttr['kind'] | undefined;
- if (!kind) throw new Error(`terraform attribute ${name}: unsupported ${v.slice(0, 40)}`);
- const element =
- kind === 'List'
- ? (/ElementType:\s*types\.(String|Int64|Bool)Type/.exec(v)?.[1] as TfAttr['element'] | undefined)
- : undefined;
- if (kind === 'List' && !element) throw new Error(`terraform attribute ${name}: unsupported list ${v.slice(0, 60)}`);
- const desc = /Description:\s*("(?:[^"\\]|\\.)*")/.exec(v);
- const oneOf = /OneOf\(([^)]*)\)/.exec(v);
- const atLeast = /AtLeast\((\d+)\)/.exec(v);
- const between = /\.Between\((\d+),\s*(\d+)\)/.exec(v);
- const length = /LengthBetween\((\d+),\s*(\d+)\)/.exec(v);
- const re = /RegexMatches\((\w+)/.exec(v);
- return {
- name,
- kind,
- element,
- required: /Required:\s*true/.test(v),
- optional: /Optional:\s*true/.test(v),
- computed: /Computed:\s*true/.test(v),
- sensitive: /Sensitive:\s*true/.test(v),
- description: desc ? goString(desc[1]) : '',
- oneOf: oneOf ? [...oneOf[1].matchAll(/"([^"]*)"/g)].map((m) => m[1]) : undefined,
- atLeast: atLeast ? Number(atLeast[1]) : undefined,
- between: between ? [Number(between[1]), Number(between[2])] : undefined,
- length: length ? [Number(length[1]), Number(length[2])] : undefined,
- pattern: re ? regexes.get(re[1]) : undefined,
- requiresReplace: /RequiresReplace\(\)/.test(v),
- json: /jsontypes\.NormalizedType/.test(v),
- };
-}
-
-export function parseTfSchema(src: string, fnName: string): TfSchema {
- const regexes = new Map<string, string>();
- for (const m of src.matchAll(/var (\w+) = regexp\.MustCompile\(`([^`]*)`\)/g)) regexes.set(m[1], m[2]);
- const fn = src.indexOf(`func ${fnName}(`);
- if (fn < 0) throw new Error(`terraform: ${fnName} not found`);
- const fnBody = src.slice(fn, matchBrace(src, src.indexOf('{', fn)) + 1);
- const description = /Description:\s*("(?:[^"\\]|\\.)*")/.exec(fnBody);
- const attrsAt = fnBody.indexOf('Attributes: map[string]schema.Attribute{');
- const attrs = goMapEntries(fnBody, fnBody.indexOf('{', attrsAt + 'Attributes: map[string]schema.Attribute'.length)).map(
- ([k, v]) => tfAttr(k, v, regexes)
- );
- const blocks: TfBlock[] = [];
- const blocksAt = fnBody.indexOf('Blocks: map[string]schema.Block{');
- if (blocksAt >= 0) {
- for (const [k, v] of goMapEntries(fnBody, fnBody.indexOf('{', blocksAt + 'Blocks: map[string]schema.Block'.length))) {
- const nesting = /^schema\.SetNestedBlock/.test(v) ? 'set' : /^schema\.SingleNestedBlock/.test(v) ? 'single' : null;
- if (!nesting) throw new Error(`terraform block ${k}: unsupported ${v.slice(0, 40)}`);
- const at = v.indexOf('Attributes: map[string]schema.Attribute{');
- const nested = goMapEntries(v, v.indexOf('{', at + 'Attributes: map[string]schema.Attribute'.length)).map(([n, a]) =>
- tfAttr(n, a, regexes)
- );
- blocks.push({ name: k, nesting, attrs: nested });
- }
- }
- return { description: description ? goString(description[1]) : '', attrs, blocks };
-}
-
-/** `- \`name\` - text` argument lines of the provider's registry docs. */
-export function parseTfDocs(md: string): { args: Map<string, string>; importCode?: string } {
- const args = new Map<string, string>();
- for (const m of md.matchAll(/^- `([\w.]+)`(?: \/ `([\w.]+)`)? - (.+)$/gm)) {
- args.set(m[1], m[3].trim());
- if (m[2]) args.set(m[2], m[3].trim());
- }
- const imp = /## Import\s*\n+```\w*\n([\s\S]*?)```/.exec(md);
- return { args, importCode: imp?.[1].trim() };
-}
-
-interface TfMapping {
- attributes: Array<{ name: string; cr?: string; crd_path?: string }>;
- blocks: Array<{
- name: string;
- cr: string;
- crd_path: string;
- collection: string;
- fields: Array<{ name: string; crd_path: string }>;
- }>;
-}
-
-// ----------------------------------------------------------------- errors
-
-export interface ErrorEntry {
- name: string;
- message: string;
- doc: string;
- surfaces?: string;
-}
-
-/** `cua_fleet::Error::X => Error::Y` arms of cua-daemon's `From<cua_fleet::Error>`. */
-/** Variants `cua_fleet::Error::is_not_found` can answer true for. */
-export function notFoundVariants(src: string): Set<string> {
- const at = src.indexOf('pub fn is_not_found(&self) -> bool');
- if (at < 0) throw new Error('cua-fleet: is_not_found not found');
- const open = src.indexOf('{', at);
- const body = src.slice(open, matchBrace(src, open));
- return new Set([...body.matchAll(/Error::(\w+)[^=]*=>\s*(?!false)/g)].map((m) => m[1]));
-}
-
-export function daemonMapping(src: string): { map: Map<string, string>; notFound: string; other: string; guest: string[] } {
- const at = src.indexOf('impl From<cua_fleet::Error> for Error');
- if (at < 0) throw new Error('cua-daemon: From<cua_fleet::Error> not found');
- const open = src.indexOf('{', src.indexOf('match e', at));
- const body = src.slice(open, matchBrace(src, open));
- const map = new Map<string, string>();
- for (const m of body.matchAll(/cua_fleet::Error::(\w+)[^=]*=>\s*(?:\{\s*)?Error::(\w+)/g)) map.set(m[1], m[2]);
- const notFound = /is_not_found\(\)\s*=>\s*Error::(\w+)/.exec(body)?.[1];
- const other = /other\s*=>\s*Error::(\w+)/.exec(body)?.[1];
- if (!notFound || !other) throw new Error('cua-daemon: fleet error mapping changed');
- const g = src.indexOf('impl From<cua_spacesd_client::Error> for Error');
- const gOpen = src.indexOf('{', src.indexOf('match e', g));
- const guest = [...new Set([...src.slice(gOpen, matchBrace(src, gOpen)).matchAll(/=>\s*(?:\{\s*)?Error::(\w+)/g)].map((m) => m[1]))];
- if (g < 0 || !guest.length) throw new Error('cua-daemon: guest error mapping changed');
- return { map, notFound, other, guest };
-}
-
-// ------------------------------------------------------------ the objects
-
-type RestRef = { client: string } | { swagger: string; method: string };
-
-interface ObjectDef {
- slug: string;
- title: string;
- /** One line for the index and the page description. */
- summary: string;
- task: string;
- crd?: string;
- schema?: 'image';
- rest: Array<RestRef & { title?: string }>;
- sdk: string[];
- terraform?: 'pool' | 'template';
- extensionsFor?: string;
- example?: 'pool' | 'template' | 'claim';
-}
-
-const K8S_PASSTHROUGH = '/api/k8s/{path}';
-
-export const OBJECTS: ObjectDef[] = [
- {
- slug: 'pool',
- title: 'Pool',
- summary: 'Warm capacity: how many sandboxes of one template Fleet keeps ready to claim.',
- task: 'Keep capacity',
- crd: 'OSGymSandboxWarmPool',
- rest: ['create_pool', 'list_pools', 'get_pool', 'update_pool', 'delete_pool'].map((client) => ({ client })),
- sdk: [
- 'Fleet.apply_pool',
- 'Fleet.apply',
- 'Fleet.get_pool',
- 'Fleet.list_pools',
- 'Fleet.set_pool_replicas',
- 'Fleet.wait_pool_ready',
- 'Fleet.export_pool',
- 'Fleet.delete_pool',
- 'Fleet.ephemeral_pool_name',
- 'Fleet.pools',
- 'FleetPools.list',
- 'FleetPools.gc',
- 'FleetPools.gc_pools',
- ],
- terraform: 'pool',
- example: 'pool',
- },
- {
- slug: 'template',
- title: 'Template',
- summary: "What each sandbox of a pool runs: image, runtime, size, services and probes.",
- task: 'Keep capacity',
- crd: 'OSGymSandboxTemplate',
- rest: ['create_template', 'list_templates', 'get_template', 'update_template', 'delete_template'].map((client) => ({
- client,
- })),
- sdk: ['Fleet.apply_pool_template', 'Fleet.check_pool_spec', 'Fleet.list_templates'],
- terraform: 'template',
- extensionsFor: 'Template',
- example: 'template',
- },
- {
- slug: 'claim',
- title: 'Claim',
- summary: 'A lease on one sandbox from a pool, until it is released or expires.',
- task: 'Use a sandbox',
- crd: 'OSGymSandboxClaim',
- rest: ['create_claim', 'list_claims', 'get_claim', 'renew_claim', 'delete_claim'].map((client) => ({ client })),
- sdk: [
- 'Fleet.acquire',
- 'Fleet.acquire_with',
- 'Fleet.claim',
- 'Fleet.attach_claim',
- 'Fleet.list_claims',
- 'Fleet.keep_alive',
- 'Fleet.release',
- ],
- extensionsFor: 'Claim',
- example: 'claim',
- },
- {
- slug: 'sandbox',
- title: 'Sandbox',
- summary: 'One running machine of a pool, bound to at most one claim.',
- task: 'Use a sandbox',
- crd: 'OSGymSandbox',
- rest: [],
- sdk: ['Fleet.attach_claim', 'Fleet.service_url'],
- },
- {
- slug: 'secret',
- title: 'Secret',
- summary: "Secrets the SDK writes in a pool's namespace: a claim's env token and registry pull credentials.",
- task: 'Use a sandbox',
- rest: [],
- sdk: [],
- },
- {
- slug: 'service-url',
- title: 'Service URL',
- summary: "HTTP and WebSocket access to a sandbox's services, and shareable signed URLs.",
- task: 'Use a sandbox',
- rest: [
- { swagger: '/api/svc/{namespace}/{service}/{path}', method: 'get', title: 'Call a service' },
- { swagger: '/api/signed-service-urls/{namespace}', method: 'post', title: 'Create a signed URL' },
- { swagger: '/api/signed-service-urls/{namespace}', method: 'get', title: 'List signed URLs' },
- { swagger: '/api/signed-service-urls/{namespace}/{id}', method: 'delete', title: 'Revoke a signed URL' },
- ],
- sdk: ['Fleet.service_url', 'Fleet.create_signed_service_url'],
- },
- {
- slug: 'image',
- title: 'Image',
- summary: 'A build recipe Fleet turns into a runnable image, and its build status.',
- task: 'Build images',
- schema: 'image',
- rest: [
- { client: 'create_image' },
- { client: 'list_images' },
- { client: 'get_image' },
- { client: 'delete_image' },
- { client: 'presign_image_uploads' },
- ],
- sdk: ['Fleet.create_image', 'Fleet.list_images', 'Fleet.get_image', 'Fleet.delete_image'],
- },
- {
- slug: 'namespace',
- title: 'Namespace',
- summary: 'The account-owned scope every pool, template, claim and secret lives in.',
- task: 'Account',
- rest: [
- { swagger: '/api/namespaces', method: 'post', title: 'Create a namespace' },
- { swagger: '/api/namespaces', method: 'get', title: 'List namespaces' },
- { swagger: '/api/namespaces/{name}', method: 'get', title: 'Get a namespace' },
- { swagger: '/api/namespaces/{name}', method: 'delete', title: 'Delete a namespace' },
- ],
- sdk: [],
- },
- {
- slug: 'api-key',
- title: 'API key',
- summary: 'OAuth client credentials that act for your user, for the SDK, CLI and Terraform.',
- task: 'Account',
- rest: [
- { swagger: '/api/user-keys', method: 'post', title: 'Create an API key' },
- { swagger: '/api/user-keys', method: 'get', title: 'List API keys' },
- { swagger: '/api/user-keys/{id}', method: 'delete', title: 'Revoke an API key' },
- ],
- sdk: [],
- },
-];
-
-// ------------------------------------------------------------ rendering
-
-interface Ctx {
- dump: FleetDump;
- routes: Map<string, string>;
- ops: Map<string, ClientOp>;
- swagger: Swagger;
- handle: Map<string, HandleMethod>;
- tf: TfSchema;
- tfProvider: TfSchema;
- tfDocs: { args: Map<string, string>; importCode?: string };
- tfMapping: TfMapping;
- tfSource: string;
- tfExample?: { code: string; source: string };
- imageSchema: Schema;
- secretRoute: string;
- errors: { fleet: ErrorEntry[]; sdk: ErrorEntry[] };
- descriptions: Descriptions;
- version: string;
-}
-
-function crdOf(ctx: Ctx, kind: string): Crd {
- const crd = ctx.dump.crds.find((c) => c.spec.names.kind === kind);
- if (!crd) throw new Error(`CRD ${kind} missing from the dump`);
- return crd;
-}
-
-/** A CRD's fields with the public descriptions applied (a sandbox shares its template's `spec`). */
-function crdFields(ctx: Ctx, kind: string) {
- const fields = flattenSchema(crdSchema(crdOf(ctx, kind)));
- const own = ctx.descriptions.crd[kind] ?? {};
- const out = applyOverrides(fields, own, kind);
- if (kind === 'OSGymSandbox') {
- const shared = ctx.descriptions.crd.OSGymSandboxTemplate ?? {};
- return applyOverrides(out, shared, kind, false).map((f) => (own[f.path] ? { ...f, description: own[f.path] } : f));
- }
- return out;
-}
-
-function crdSchema(crd: Crd): Schema {
- return crd.spec.versions[0].schema.openAPIV3Schema;
-}
-
-function apiVersion(crd: Crd): string {
- return `${crd.spec.group}/${crd.spec.versions[0].name}`;
-}
-
-const lower = (s: string) => s.charAt(0).toLowerCase() + s.slice(1);
-const cap = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
-
-function objectAnchor(def: ObjectDef): string {
- return slug(`The ${lower(def.title)} object`);
-}
-
-function sdkCell(ctx: Ctx, key: string): string {
- const m = ctx.handle.get(key);
- if (!m) throw new Error(`SDK method ${key} not found in cua-sdk native/fleet.rs`);
- const sig = `${key}(${m.params.join(', ')})`;
- return m.href ? `[${codeCell(sig)}](${m.href})` : codeCell(sig);
-}
-
-function restHeading(ctx: Ctx, ref: RestRef & { title?: string }): string {
- if ('client' in ref) {
- const op = ctx.ops.get(ref.client);
- if (!op) throw new Error(`Fleet client method ${ref.client} not found`);
- return ref.title ?? cap(op.op);
- }
- const op = swaggerOp(ctx, ref.swagger, ref.method);
- return ref.title ?? op.summary;
-}
-
-function swaggerOp(ctx: Ctx, p: string, method: string): SwaggerOp {
- const op = ctx.swagger.paths[p]?.[method];
- if (!op) throw new Error(`swagger: ${method.toUpperCase()} ${p} not found`);
- return op;
-}
-
-function restLine(ctx: Ctx, ref: RestRef): string {
- if ('client' in ref) {
- const op = ctx.ops.get(ref.client)!;
- return `${op.method} ${op.path}`;
- }
- return `${ref.method.toUpperCase()} ${ref.swagger}`;
-}
-
-function pathParams(p: string): string[] {
- return [...p.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
-}
-
-const PARAM_DOCS: Record<string, string> = {
- namespace: "The pool's namespace. A pool, its namespace and its template share one name.",
- name: 'The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters).',
- service: 'The Kubernetes Service of the sandbox service: `<sandbox>-<service>`.',
- path: 'The upstream path, forwarded verbatim (it must start with `/`).',
- id: 'The object id.',
- claim: 'The claim name.',
-};
-
-function definitionRef(ref?: string): string | undefined {
- return ref?.replace(/^#\/definitions\//, '');
-}
-
-function schemaRows(ctx: Ctx, def: string, intro: string): string[] {
- const schema = ctx.swagger.definitions[def];
- if (!schema) throw new Error(`swagger definition ${def} missing`);
- const fields = applyOverrides(
- flattenSchema(schema, { ...schema, definitions: ctx.swagger.definitions } as Schema),
- ctx.descriptions.swagger[def] ?? {},
- def
- );
- if (fields.every((f) => !f.description && !f.constraints.length)) {
- const list = fields.map((f) => `${codeCell(f.path)} (${f.type})`).join(', ');
- return [`${intro} an object with ${list}.`, ''];
- }
- return [`${intro}:`, '', ...fieldTable(fields)];
-}
-
-function renderRest(ctx: Ctx, def: ObjectDef): string[] {
- if (!def.rest.length) return [];
- const out = ['## REST', ''];
- const errorsLink = '[Errors](/fleets/reference/errors#http-status-codes)';
- for (const ref of def.rest) {
- out.push(`### ${restHeading(ctx, ref)}`, '');
- out.push(codeFence('http', restLine(ctx, ref)), '');
- if ('client' in ref) {
- const op = ctx.ops.get(ref.client)!;
- if (op.doc) out.push(escapeMdxText(flattenRustdocLinks(op.doc.replace(/\s*\n\s*/g, ' '))), '');
- if (/\{name\}\/\w+\/\{name\}/.test(op.path))
- out.push("A pool's namespace is its name, so the name fills both slots.", '');
- const params = [...new Set(pathParams(op.path))];
- if (params.length) {
- out.push('| Parameter | In | Description |', '| --- | --- | --- |');
- for (const p of params) {
- const where = op.path.includes(`?${p}=`) ? 'query' : 'path';
- out.push(`| ${codeCell(p)} | ${where} | ${escapeTableCell(PARAM_DOCS[p] ?? '')} |`);
- }
- out.push('');
- }
- const isItem = /\{name\}$/.test(op.path);
- const objectLink = def.crd || def.schema ? `[${lower(def.title)} object](#${objectAnchor(def)})` : 'object';
- if (ref.client === 'presign_image_uploads') {
- out.push(...presignBody(ctx));
- } else {
- const body =
- op.method === 'POST'
- ? `Body: the ${objectLink} (\`application/json\`).`
- : op.method === 'PATCH'
- ? `Body: a JSON merge patch of the ${objectLink} (\`application/merge-patch+json\`).`
- : '';
- if (body) out.push(body, '');
- const ok = op.statuses.filter((s) => s < 400);
- const tolerated = op.statuses.filter((s) => s >= 400);
- const returns =
- op.method === 'DELETE'
- ? 'with no body'
- : op.method === 'GET' && !isItem
- ? `with \`{"items": [...]}\`, a list of the ${objectLink}`
- : `with the ${objectLink}`;
- out.push(`Returns: ${ok.map((s) => `\`${s}\``).join(', ')} ${returns}.`, '');
- if (tolerated.length)
- out.push(`${tolerated.map((s) => `\`${s}\``).join(', ')} is treated as success: the object is already gone.`, '');
- }
- if (op.calls.includes('create_namespace_if_missing'))
- out.push(
- 'The SDK first creates the namespace named after the pool ([Create a namespace](/fleets/reference/namespace#create-a-namespace)) and deletes it again if the pool is refused.',
- ''
- );
- if (op.calls.includes('delete_namespace') && !op.calls.includes('create_namespace_if_missing'))
- out.push('The SDK then deletes the namespace, with everything left in it.', '');
- if (op.path.startsWith('/api/k8s/')) {
- const passthrough = swaggerOp(ctx, K8S_PASSTHROUGH, 'get');
- out.push(`Errors: ${errorStatuses(passthrough)} (${errorsLink}).`, '');
- } else out.push(`Errors: see ${errorsLink}.`, '');
- } else {
- const op = swaggerOp(ctx, ref.swagger, ref.method);
- if (op.description && ref.swagger.startsWith('/api/signed-service-urls'))
- out.push(escapeMdxText(cleanDescription(op.description)), '');
- const params = (op.parameters ?? []).filter((p) => p.in !== 'body');
- if (params.length) {
- out.push('| Parameter | In | Description |', '| --- | --- | --- |');
- for (const p of params)
- out.push(
- `| ${codeCell(p.name)} | ${p.in} | ${escapeTableCell(
- [PARAM_DOCS[p.name] ?? cleanDescription(p.description), p.required ? '' : 'Optional.']
- .filter(Boolean)
- .join(' ')
- )} |`
- );
- out.push('');
- }
- const body = (op.parameters ?? []).find((p) => p.in === 'body');
- const bodyDef = definitionRef(body?.schema?.$ref);
- if (bodyDef) out.push(...schemaRows(ctx, bodyDef, 'Body (`application/json`)'));
- const okEntry = Object.entries(op.responses).find(([s]) => Number(s) < 400);
- if (okEntry) {
- const [status, r] = okEntry;
- const itemsRef = definitionRef((r.schema?.items as { $ref?: string } | undefined)?.$ref);
- const ref = definitionRef(r.schema?.$ref);
- if (ref) out.push(...schemaRows(ctx, ref, `Returns: \`${status}\` with`));
- else if (itemsRef) out.push(...schemaRows(ctx, itemsRef, `Returns: \`${status}\` with an array; each item is`));
- else out.push(`Returns: \`${status}\`. ${escapeMdxText(r.description)}.`, '');
- }
- out.push(`Errors: ${errorStatuses(op)} (${errorsLink}).`, '');
- }
- }
- return out;
-}
-
-function errorStatuses(op: SwaggerOp): string {
- return Object.keys(op.responses)
- .filter((s) => Number(s) >= 400)
- .map((s) => `[\`${s}\`](/fleets/reference/errors#http-${s})`)
- .join(', ');
-}
-
-function presignBody(ctx: Ctx): string[] {
- const src = read(path.join(SOURCES.sdkDir, 'image_uploads.rs'));
- // The request types carry no doc comments: list their fields inline.
- const fields = (name: string) =>
- structFields(src, name)
- .map((f) => `${codeCell(f.name)} (${jsonTypeOfRust(f.type).replace(/^ImageUploadFileRequest/, 'object').replace(/^PresignedPut$/, 'object')})`)
- .join(', ');
- void ctx;
- return [
- `Body (\`application/json\`): ${fields('ImageUploadRequest')}. Each of \`files[]\` has ${fields('ImageUploadFileRequest')}: the file's SHA-256 digest, size and name.`,
- '',
- `Returns: \`200\` with \`files[]\`, one instruction per file: ${fields('ImageUploadInstruction')}. \`reference\` is what an image recipe's \`files[].source.reference\` names. \`upload\` (${fields('PresignedPut')}) is a presigned request to send the bytes with; it is absent when Fleet already has the file.`,
- '',
- ];
-}
-
-function renderSdk(ctx: Ctx, def: ObjectDef): string[] {
- if (!def.sdk.length) return [];
- const out = [
- '## SDK',
- '',
- 'Methods of the `Fleet` handle (`cua.fleet()`), with signatures in every language in the [Cua SDK reference](/cua-sdk/reference).',
- '',
- '| Method | Returns | Description |',
- '| --- | --- | --- |',
- ];
- for (const key of def.sdk) {
- const m = ctx.handle.get(key)!;
- if (!m) throw new Error(`SDK method ${key} not found`);
- out.push(`| ${sdkCell(ctx, key)} | ${neutralType(m.returns)} | ${escapeTableCell(m.summary)} |`);
- }
- return [...out, ''];
-}
-
-/** A Rust return type as the bindings show it: `FleetPool[]`, `string`, none. */
-export function neutralType(t: string): string {
- const s = t.replace(/\s+/g, '');
- if (s === '()') return 'none';
- const vec = /^Vec<(.+)>$/.exec(s);
- if (vec) return codeCell(`${neutralType(vec[1]).replace(/`/g, '')}[]`);
- const opt = /^Option<(.+)>$/.exec(s);
- if (opt) return codeCell(`${neutralType(opt[1]).replace(/`/g, '')}?`);
- if (s === 'String') return codeCell('string');
- if (s === 'bool') return codeCell('bool');
- if (/^[ui](8|16|32|64)$/.test(s)) return codeCell('integer');
- return codeCell(s);
-}
-
-function tfType(a: TfAttr): string {
- if (a.json) return 'string (JSON)';
- const scalar = { String: 'string', Int64: 'number', Bool: 'bool' } as const;
- if (a.kind === 'List') return `list(${scalar[a.element!]})`;
- return scalar[a.kind];
-}
-
-function tfDefault(ctx: Ctx, a: TfAttr, crdPath?: { cr?: string; path?: string }): string {
- if (a.required) return 'required';
- if (crdPath?.cr && crdPath.path) {
- const kind = crdPath.cr === 'warmpool' ? 'OSGymSandboxWarmPool' : 'OSGymSandboxTemplate';
- const f = crdFields(ctx, kind).find((x) => x.path === crdPath.path);
- if (f?.default !== undefined) return codeCell(JSON.stringify(f.default));
- }
- return 'none';
-}
-
-function tfDescription(ctx: Ctx, a: TfAttr, docKey: string, crd?: { cr?: string; path?: string }): string {
- let text = ctx.tfDocs.args.get(docKey) ?? cleanDescription(a.description);
- if (!text && crd?.cr && crd.path) {
- const kind = crd.cr === 'warmpool' ? 'OSGymSandboxWarmPool' : 'OSGymSandboxTemplate';
- text = crdFields(ctx, kind).find((x) => x.path === crd.path)?.description ?? '';
- }
- const notes: string[] = [];
- const says = (v: string) => text.toLowerCase().includes(v.toLowerCase());
- if (a.oneOf && !a.oneOf.every((v) => says(`\`${v}\``))) notes.push(`One of ${a.oneOf.map((v) => `\`${v}\``).join(', ')}.`);
- if (a.length) notes.push(`${a.length[0]} to ${a.length[1]} characters.`);
- if (a.pattern) notes.push(`Matches ${codeCell(a.pattern)}.`);
- if (a.atLeast !== undefined) notes.push(`At least ${a.atLeast}.`);
- if (a.between) notes.push(`${a.between[0]} to ${a.between[1]}.`);
- if (a.requiresReplace && !says('replaces the resource')) notes.push('Changing it replaces the resource.');
- if (a.sensitive) notes.push('Sensitive.');
- return [escapeTableCell(text), ...notes].filter(Boolean).join(' ');
-}
-
-function tfTable(ctx: Ctx, attrs: TfAttr[], crdOfAttr: (a: TfAttr) => { cr?: string; path?: string } | undefined, prefix = ''): string[] {
- const rows = ['| Argument | Type | Default | Description |', '| --- | --- | --- | --- |'];
- for (const a of attrs) {
- const crd = crdOfAttr(a);
- rows.push(
- `| ${codeCell(prefix + a.name)} | ${codeCell(tfType(a))} | ${tfDefault(ctx, a, crd)} | ${tfDescription(ctx, a, prefix + a.name, crd)} |`
- );
- }
- return [...rows, ''];
-}
-
-function mappingFor(ctx: Ctx, name: string, block?: string): { cr?: string; path?: string } | undefined {
- if (block) {
- const b = ctx.tfMapping.blocks.find((x) => x.name === block);
- const f = b?.fields.find((x) => x.name === name);
- return b && f ? { cr: b.cr, path: `${b.crd_path}${b.collection === 'set' ? '[]' : ''}.${f.crd_path}` } : undefined;
- }
- const a = ctx.tfMapping.attributes.find((x) => x.name === name);
- return a?.cr ? { cr: a.cr, path: a.crd_path } : undefined;
-}
-
-function renderTerraform(ctx: Ctx, def: ObjectDef): string[] {
- if (def.terraform === 'template') {
- const rows = ['| Terraform argument | Template field |', '| --- | --- |'];
- for (const a of ctx.tfMapping.attributes.filter((x) => x.cr === 'template'))
- rows.push(`| [${codeCell(a.name)}](/fleets/reference/pool#terraform) | ${codeCell(a.crd_path!)} |`);
- for (const b of ctx.tfMapping.blocks.filter((x) => x.cr === 'template'))
- rows.push(`| [${codeCell(`${b.name} {}`)}](/fleets/reference/pool#terraform) | ${codeCell(b.crd_path)} |`);
- return [
- '## Terraform',
- '',
- 'Terraform manages the template as part of its pool: [`fleets_pool`](/fleets/reference/pool#terraform) writes a template named `<pool>-template` from these arguments.',
- '',
- ...rows,
- '',
- ];
- }
- if (def.terraform !== 'pool') return [];
- const tf = ctx.tf;
- const inputs = tf.attrs.filter((a) => a.required || a.optional);
- const computed = tf.attrs.filter((a) => a.computed && !a.required && !a.optional);
- const out = ['## Terraform', '', `Resource \`fleets_pool\` of the [\`trycua/fleets\` provider](/fleets/reference/terraform). ${escapeMdxText(tf.description)}`, ''];
- if (ctx.tfExample) {
- out.push(
- `{/* Example source: ${ctx.tfExample.source} (tested by the docs terraform lane) */}`,
- '',
- codeFence('hcl', ctx.tfExample.code, 'title="main.tf"'),
- ''
- );
- }
- out.push('### Arguments', '', 'Exactly one of `replicas` or `autoscaling` is required.', '');
- out.push(...tfTable(ctx, inputs, (a) => mappingFor(ctx, a.name)));
- for (const b of tf.blocks) {
- const kind = b.nesting === 'set' ? 'Repeatable block' : 'Block';
- out.push(`### \`${b.name}\` block`, '', `${kind}. ${escapeTableCell(ctx.tfDocs.args.get(b.name) ?? '')}`.trim(), '');
- out.push(...tfTable(ctx, b.attrs, (a) => mappingFor(ctx, a.name, b.name), `${b.name}.`));
- }
- out.push('### Attributes', '', 'Read-only, set by the provider.', '', '| Attribute | Type | Description |', '| --- | --- | --- |');
- for (const a of computed) {
- const crd = mappingFor(ctx, a.name);
- const d = tfDescription(ctx, a, a.name, crd) || (a.name === 'id' ? 'The pool name.' : a.name === 'namespace' ? "The pool's namespace (the pool name)." : '');
- out.push(`| ${codeCell(a.name)} | ${codeCell(tfType(a))} | ${d} |`);
- }
- out.push('', '`replicas` is also set in autoscaling mode: it reports the current pool target.', '');
- if (ctx.tfDocs.importCode) out.push('### Import', '', 'Import IDs are pool names.', '', codeFence('shell', ctx.tfDocs.importCode), '');
- return out;
-}
-
-function renderObjectFields(ctx: Ctx, def: ObjectDef): string[] {
- const out: string[] = [];
- if (def.crd) {
- const crd = crdOf(ctx, def.crd);
- const fields = crdFields(ctx, def.crd).filter((f) => f.path !== 'spec' && f.path !== 'status');
- const spec = fields.filter((f) => f.path.startsWith('spec.'));
- const status = fields.filter((f) => f.path.startsWith('status.'));
- out.push(
- `## The ${lower(def.title)} object`,
- '',
- `\`apiVersion: ${apiVersion(crd)}\`, \`kind: ${crd.spec.names.kind}\`, in the pool's namespace. Plural \`${crd.spec.names.plural}\`${
- crd.spec.names.shortNames?.length ? `, short name \`${crd.spec.names.shortNames.join('`, `')}\`` : ''
- }. \`metadata\` is standard Kubernetes object metadata (\`name\`, \`namespace\`, \`labels\`).`,
- ''
- );
- out.push('### Spec', '', ...fieldTable(spec));
- if (status.length) out.push('### Status', '', 'Set by Fleet; read-only.', '', ...fieldTable(status));
- } else if (def.schema === 'image') {
- const root = ctx.imageSchema;
- out.push(
- `## The ${lower(def.title)} object`,
- '',
- `${escapeMdxText(cleanDescription(root.description))} \`apiVersion: images.cua.ai/v1alpha1\`, \`kind: Image\`. The same resource \`cua image build\` reads from \`image.json\`.`,
- ''
- );
- if (!ctx.dump.config.remote_builds_supported)
- out.push(
- 'Fleet does not build `kind: container` recipes yet: a cloud Image with layers fails with a clear error. Build it locally and push it to a registry instead.',
- ''
- );
- const all = flattenSchema(root).filter((f) => !['apiVersion', 'kind', 'metadata', 'spec', 'status'].includes(f.path));
- out.push('### Metadata and spec', '', ...fieldTable(all.filter((f) => !f.path.startsWith('status'))));
- out.push('### Status', '', 'Set by Fleet; read-only.', '', ...fieldTable(all.filter((f) => f.path.startsWith('status'))));
- out.push(...layerTypes(root));
- }
- if (def.extensionsFor) {
- const ext = ctx.dump.extensions.filter((e) => e.object === def.extensionsFor);
- if (ext.length) {
- out.push(
- '### Fields the SDK adds',
- '',
- 'Written as JSON beyond the published schema; Fleet reads them.',
- '',
- '| Field | Type | Description |',
- '| --- | --- | --- |'
- );
- for (const e of ext) out.push(`| ${codeCell(e.field)} | ${codeCell(e.type)} | ${escapeTableCell(e.description)} |`);
- out.push('');
- }
- }
- if (def.example) {
- out.push(
- '### Example',
- '',
- `What the SDK sends for a default pool of the cua Linux image (\`PoolSpec::new\`, built by \`cua-fleet\`).`,
- '',
- codeFence('json', JSON.stringify(ctx.dump.examples[def.example], null, 2)),
- ''
- );
- }
- return out;
-}
-
-function layerTypes(root: Schema): string[] {
- const recipe = flattenSchema(root).find((f) => f.path.endsWith('recipe.layers'));
- if (!recipe) return [];
- const spec = root.$defs?.ImageLayer;
- if (!spec) return [];
- const tagged = taggedVariants(spec, root);
- if (!tagged) return [];
- const out = ['### Layer types', '', '`spec.recipe.layers[]` holds build steps, each tagged by `type`.', '', '| `type` | Fields |', '| --- | --- |'];
- for (const v of tagged) {
- const fields = Object.entries(v.schema.properties ?? {})
- .filter(([k]) => k !== v.key)
- .map(([k, p]) => `${codeCell(k)} ${codeCell(typeOf(p, root))}`);
- out.push(`| ${codeCell(v.tag)} | ${fields.join(', ')} |`);
- }
- return [...out, ''];
-}
-
-function renderSecret(ctx: Ctx): string[] {
- const c = ctx.dump.secrets.claim;
- const r = ctx.dump.secrets.registry;
- return [
- '## Claim secret',
- '',
- `Every claim the SDK makes carries a fresh env token for the sandbox's cua-spacesd. The SDK writes it as an Opaque Secret \`${c.prefix}<claim>\` (key \`${c.key}\`, label \`${c.label}: <claim>\`), then creates the claim with \`spec.secretRef\` naming it. Fleet delivers it into the bound sandbox at \`/run/cua/env-token\`; the token never crosses the network to the guest. After the claim binds, the SDK waits up to ${c.wait_seconds} seconds for the guest to accept the token, then releases the claim with [\`ClaimSecretsNotDelivered\`](/fleets/reference/errors#claimsecretsnotdelivered).`,
- '',
- codeFence('json', JSON.stringify(c.example, null, 2)),
- '',
- '## Registry pull secret',
- '',
- `Credentials for a private registry, written as a \`kubernetes.io/dockerconfigjson\` Secret \`${r.prefix}<16 hex>\` (a hash of registry and user, so a new password updates the same Secret) and named by the template's \`imagePullSecret\`.`,
- '',
- codeFence('json', JSON.stringify(r.example, null, 2)),
- '',
- '## REST',
- '',
- 'Secrets are core Kubernetes objects behind the same proxy as the Fleet resources.',
- '',
- '### Create a secret',
- '',
- codeFence('http', `POST ${ctx.secretRoute}`),
- '',
- 'Body: the Secret. `409` means a Secret of that name exists (another claim attempt); the SDK does not overwrite it.',
- '',
- '### Delete a secret',
- '',
- codeFence('http', `DELETE ${ctx.secretRoute}/{name}`),
- '',
- '`404` is treated as success. The SDK deletes a claim\'s Secret when it releases the claim.',
- '',
- `Errors: ${errorStatuses(swaggerOp(ctx, K8S_PASSTHROUGH, 'get'))} ([Errors](/fleets/reference/errors#http-status-codes)).`,
- '',
- ];
-}
-
-function renderSandboxExtras(): string[] {
- return [
- 'A sandbox is created by its pool, never directly. `status.sandbox` of a bound [claim](/fleets/reference/claim) names it; the SDK returns it as a `FleetSandbox` (namespace, claim, name and services).',
- '',
- ];
-}
-
-function renderObjectPage(ctx: Ctx, def: ObjectDef): string {
- const body: string[] = [];
- if (def.slug === 'sandbox') body.push(...renderSandboxExtras());
- if (def.rest.length || def.sdk.length) {
- const sections = [
- def.crd || def.schema ? `[Object](#${objectAnchor(def)})` : '',
- def.rest.length ? '[REST](#rest)' : '',
- def.sdk.length ? '[SDK](#sdk)' : '',
- def.terraform ? '[Terraform](#terraform)' : '',
- ].filter(Boolean);
- body.push(`On this page: ${sections.join(' · ')}`, '');
- }
- body.push(...renderObjectFields(ctx, def));
- if (def.slug === 'secret') body.push(...renderSecret(ctx));
- body.push(...renderRest(ctx, def), ...renderSdk(ctx, def), ...renderTerraform(ctx, def));
- return renderPage({
- title: def.title,
- description: def.summary,
- generator: REGENERATE,
- source: pageSource(def),
- version: ctx.version,
- body: body.join('\n'),
- });
-}
-
-function pageSource(def: ObjectDef): string {
- const s: string[] = [];
- if (def.crd) s.push('cua-fleet fleet-docs-dump (osgym.cua.ai CRDs)');
- if (def.schema === 'image') s.push('cua-image schema/image-v1alpha1.schema.json');
- if (def.slug === 'secret') s.push('cua-fleet fleet-docs-dump (secrets)');
- if (def.rest.some((r) => 'client' in r)) s.push('libs/fleet/sdk/src (routes, methods)');
- if (def.rest.some((r) => 'swagger' in r) || def.rest.length) s.push('libs/fleet/backend/docs/swagger.json');
- if (def.sdk.length) s.push('cua-sdk src/native/fleet.rs');
- if (def.terraform) s.push('terraform-provider-fleets schema');
- return s.join('; ');
-}
-
-function renderIndex(ctx: Ctx): string {
- const sec = ctx.swagger.securityDefinitions.BearerAuth;
- const body: string[] = [
- 'Everything Cua Fleets exposes, by object: the REST resources behind the Fleet API, the SDK `Fleet` handle, and the `trycua/fleets` Terraform provider.',
- '',
- '## Objects',
- '',
- '| Task | Object | Description |',
- '| --- | --- | --- |',
- ];
- for (const def of OBJECTS)
- body.push(`| ${def.task} | [${def.title}](/fleets/reference/${def.slug}) | ${escapeTableCell(def.summary)} |`);
- body.push(
- `| Configure | [Terraform provider](/fleets/reference/terraform) | Provider settings and the resources it manages. |`,
- `| Debug | [Errors](/fleets/reference/errors) | HTTP statuses and SDK errors, with causes and fixes. |`,
- ''
- );
- body.push(
- '## Base URL and authentication',
- '',
- `- Base URL: \`${ctx.dump.config.default_base_url}\` (\`CUA_FLEET_BASE_URL\` overrides it for the SDK).`,
- `- Every request sends \`${sec.name}: Bearer <token>\`. Exchange an [API key](/fleets/reference/api-key) for a token with the OAuth client-credentials grant at \`${ctx.dump.config.default_token_url}\`.`,
- '- The SDK and CLI read `CUA_CLIENT_ID` and `CUA_CLIENT_SECRET`, a `cua auth login` session, or `FLEETS_TOKEN`.',
- '',
- '## Conventions',
- '',
- '- Pools, templates, claims and sandboxes are Kubernetes custom resources (`osgym.cua.ai/v1alpha1`) under `/api/k8s/apis/osgym.cua.ai/v1alpha1/namespaces/{namespace}/`. Images are `images.cua.ai/v1alpha1`.',
- '- A pool owns the namespace of the same name; its template and claims live there too.',
- '- Names are DNS labels: lowercase letters, digits and `-`, at most 63 characters.',
- '- Lists return `{"items": [...]}`. Updates are JSON merge patches (`Content-Type: application/merge-patch+json`).',
- '- Errors outside the Kubernetes proxy return `{"error": "<message>"}`.',
- ''
- );
- body.push('## Operations', '', '| Object | REST | SDK | Terraform |', '| --- | --- | --- | --- |');
- for (const def of OBJECTS) {
- const rest = def.rest.map((r) => `[${restHeading(ctx, r)}](/fleets/reference/${def.slug}#${slug(restHeading(ctx, r))})`).join(', ');
- const sdk = def.sdk.filter((k) => k.startsWith('Fleet.')).map((k) => codeCell(k)).join(', ');
- const tf = def.terraform ? '`fleets_pool`' : '';
- body.push(`| [${def.title}](/fleets/reference/${def.slug}) | ${rest || 'none'} | ${sdk || 'none'} | ${tf || 'none'} |`);
- }
- body.push('');
- return renderPage({
- title: 'Reference',
- description: 'Cua Fleets objects, REST operations, SDK methods and Terraform schema.',
- generator: REGENERATE,
- source: 'fleet-docs-dump; libs/fleet (client, swagger, Terraform provider); cua-sdk native/fleet.rs',
- version: ctx.version,
- body: body.join('\n'),
- });
-}
-
-function renderTerraformPage(ctx: Ctx): string {
- const p = ctx.tfProvider;
- const envs = p.attrs.map((a) => /CYCLOPS_\w+/.exec(a.description)?.[0]).filter(Boolean);
- const body: string[] = [
- 'The `trycua/fleets` provider manages Fleet pools. Install it from the Terraform Registry with `terraform init`; OpenTofu works the same with `tofu`.',
- '',
- codeFence(
- 'hcl',
- ['terraform {', ' required_providers {', ' fleets = {', ` source = "${ctx.tfSource}"`, ' }', ' }', '}'].join('\n')
- ),
- '',
- '## Provider arguments',
- '',
- 'Use either `access_token`, or all three of `client_id`, `client_secret` and `token_url` (an [API key](/fleets/reference/api-key)). An argument wins over its environment variable.',
- '',
- '| Argument | Type | Default | Environment variable | Description |',
- '| --- | --- | --- | --- | --- |',
- ];
- for (const a of p.attrs) {
- const env = /CYCLOPS_\w+/.exec(a.description)?.[0] ?? (a.name === 'endpoint' ? 'CYCLOPS_ENDPOINT' : '');
- const desc = a.description
- .replace(/\s*May also be set with CYCLOPS_\w+\.?/, '')
- .replace(/Cyclops base URL, for example https:\/\/cyclops\.example\.com\./, `Fleet API base URL, for example \`${ctx.dump.config.default_base_url}\`.`)
- .replace(/Cyclops /g, 'Fleet ');
- out(a, env, desc);
- }
- function out(a: TfAttr, env: string, desc: string) {
- body.push(
- `| ${codeCell(a.name)} | ${codeCell(tfType(a))} | ${a.required ? 'required' : 'none'} | ${env ? codeCell(env) : 'none'} | ${escapeTableCell(desc)}${a.sensitive ? ' Sensitive.' : ''} |`
- );
- }
- void envs;
- body.push(
- '',
- '`CUA_CLIENT_ID`, `CUA_CLIENT_SECRET`, `FLEETS_TOKEN` and `cua auth login` do not configure the provider.',
- '',
- '## Resources',
- '',
- '| Resource | Manages | Reference |',
- '| --- | --- | --- |',
- `| \`fleets_pool\` | ${escapeTableCell(ctx.tf.description)} | [Pool](/fleets/reference/pool#terraform) |`,
- '',
- 'The provider has no data sources.',
- ''
- );
- return renderPage({
- title: 'Terraform provider',
- description: 'The trycua/fleets provider: settings, environment variables and resources.',
- generator: REGENERATE,
- source: 'terraform-provider-fleets internal/provider (provider.go, pool_generated.go), main.go',
- version: ctx.version,
- body: body.join('\n'),
- });
-}
-
-const HTTP_MEANING: Record<string, [cause: string, fix: string]> = {
- '400': ['The request is malformed: a missing field, a bad name, or a value out of range.', 'Check the body against the object reference; the `error` message names the field.'],
- '401': ['No token, or an expired or invalid one.', 'Send `Authorization: Bearer <token>` with a fresh token from your API key.'],
- '403': [
- 'The token is valid but may not act on this namespace, or the proxy does not allow this request. On a read, Fleet answers 403 for a namespace that no longer exists; on a pool write, the pool name belongs to another account.',
- 'Check the namespace and name. For a new pool, pick another pool name (names are unique across accounts).',
- ],
- '404': ['The object does not exist.', 'Check the name and namespace; list the collection to see what exists.'],
- '409': ['An object with that name exists.', 'Use another name, or read the existing object.'],
- '500': ['Fleet failed to process the request.', 'Retry; report persistent failures with the request and time.'],
- '502': ['Fleet could not reach the backend behind the gateway (the Kubernetes API or the sandbox service).', 'Retry. For a service URL, check that the sandbox is bound and its service is listening.'],
- '503': ['The feature is not configured in this environment (for example signed service URLs).', 'Use the SDK service URL instead, or contact support.'],
-};
-
-function renderErrorsPage(ctx: Ctx): string {
- const statuses = new Set<string>();
- for (const methods of Object.values(ctx.swagger.paths))
- for (const op of Object.values(methods))
- if (INCLUDED_TAGS.has(op.tags[0])) for (const s of Object.keys(op.responses)) if (Number(s) >= 400) statuses.add(s);
- statuses.add('404');
- statuses.add('409');
- const sorted = [...statuses].sort();
- const body: string[] = [
- 'Every error the Fleet API and the Fleet SDK layer return, with its cause and fix. SDK languages surface them as [`CuaError`](/cua-sdk/reference/errors) cases, named in each entry.',
- '',
- '## HTTP status codes',
- '',
- 'Errors from the gateway carry `{"error": "<message>"}`; errors from the Kubernetes proxy carry a Kubernetes `Status` object with `message` and `reason`.',
- '',
- '| Status | Meaning |',
- '| --- | --- |',
- ];
- for (const s of sorted) {
- const m = HTTP_MEANING[s];
- if (!m) throw new Error(`no meaning for HTTP ${s}: add it to HTTP_MEANING`);
- body.push(`| [\`${s}\`](#http-${s}) | ${escapeTableCell(m[0])} |`);
- }
- body.push('');
- for (const s of sorted) {
- const [cause, fix] = HTTP_MEANING[s];
- body.push(`### HTTP ${s}`, '', escapeMdxText(cause), '', `Fix: ${escapeMdxText(fix)}`, '');
- }
- body.push('## SDK errors', '', 'Raised by the Fleet layer of the SDK (`cua_fleet::Error`).', '');
- body.push('| Error | Surfaces as |', '| --- | --- |');
- for (const e of ctx.errors.fleet) body.push(`| [\`${e.name}\`](#${slug(e.name)}) | ${surfacesCell(e.surfaces)} |`);
- body.push('');
- for (const e of ctx.errors.fleet) body.push(...errorEntry(e));
- body.push(
- '## Fleet API client errors',
- '',
- 'The Fleet API client under the SDK (`SdkError`). They reach SDK callers through `Sdk` above: as `CuaError.NotFound` for a missing object, otherwise `CuaError.Fleet`, with this message.',
- ''
- );
- for (const e of ctx.errors.sdk) body.push(...errorEntry(e));
- return renderPage({
- title: 'Errors',
- description: 'Fleet HTTP status codes and SDK errors, with causes and fixes.',
- generator: REGENERATE,
- source: 'swagger.json responses; cua-fleet src/lib.rs Error; libs/fleet/sdk/src/error.rs SdkError; cua-daemon mapping',
- version: ctx.version,
- body: body.join('\n'),
- });
-}
-
-function errorEntry(e: ErrorEntry): string[] {
- const out = [`### ${e.name}`, ''];
- if (e.doc) out.push(escapeMdxText(flattenRustdocLinks(e.doc.replace(/\s*\n\s*/g, ' '))), '');
- if (e.message && e.message !== 'transparent') out.push(codeFence('text', messageTemplate(e.message)), '');
- if (e.surfaces) out.push(`Surfaces as ${surfacesCell(e.surfaces)}.`, '');
- return out;
-}
-
-/** `NotFound (a missing object), else Fleet` with each case as `CuaError.X` code. */
-function surfacesCell(s: string): string {
- return s.replace(/\b([A-Z]\w+)\b/g, (m) => `\`CuaError.${m}\``);
-}
-
-/** `{field:?}` and `{}` placeholders to readable `<field>` slots. */
-export function messageTemplate(msg: string): string {
- return msg.replace(/\{(\w*)(?::\?)?\}/g, (_, name: string) => (name ? `<${name}>` : '<detail>'));
-}
-
-const INCLUDED_TAGS = new Set(['passthrough', 'gateway', 'namespaces', 'signed-service-urls', 'user-keys']);
-
-// ------------------------------------------------------------------ build
-
-function tfExample(): { code: string; source: string } | undefined {
- const dir = SOURCES.fleetDocs;
- const walk = (d: string): string[] =>
- fs.existsSync(d)
- ? fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(path.join(d, e.name)) : e.name.endsWith('.mdx') ? [path.join(d, e.name)] : []))
- : [];
- for (const file of walk(dir).sort()) {
- if (file.startsWith(OUT_DIR)) continue;
- const m = /^```hcl[^\n]*test="terraform"[^\n]*id="main-tf"[^\n]*\n([\s\S]*?)^```$/m.exec(read(file));
- if (m) return { code: m[1], source: `${path.relative(DOCS_CONTENT, file).replace(/\\/g, '/')}#main-tf` };
- }
- return undefined;
-}
-
-export function buildContext(dump: FleetDump): Ctx {
- const routes = parseRoutes(read(path.join(SOURCES.sdkDir, 'routes.rs')));
- const ops = parseClientOps(SOURCES.sdkDir, routes);
- const swagger: Swagger = JSON.parse(read(SOURCES.swagger));
- const handle = parseHandle(read(SOURCES.handle), sdkAnchors(SOURCES.sdkReference));
- const providerDir = path.join(SOURCES.tfDir, 'internal', 'provider');
- const tf = parseTfSchema(read(path.join(providerDir, 'pool_generated.go')), 'poolResourceSchema');
- const providerSrc = read(path.join(providerDir, 'provider.go'));
- const schemaFn = /func \(p \*fleetsProvider\) Schema\(/.exec(providerSrc);
- if (!schemaFn) throw new Error('provider.go: Schema not found');
- const tfProvider = parseTfSchema(providerSrc.replace('func (p *fleetsProvider) Schema(', 'func providerSchema('), 'providerSchema');
- const tfSource = /Address:\s*"registry\.terraform\.io\/([^"]+)"/.exec(read(path.join(SOURCES.tfDir, 'main.go')))?.[1];
- if (!tfSource) throw new Error('terraform main.go: registry address not found');
- const claimSrc = read(SOURCES.claimSecrets);
- const secret = /format!\("\{base\}(\/api\/k8s\/api\/v1\/namespaces\/)\{ns\}(\/secrets)"\)/.exec(claimSrc);
- if (!secret) throw new Error('claim_secrets.rs: secret collection route not found');
- const daemon = daemonMapping(read(SOURCES.daemonLib));
- const fleetSrc = read(SOURCES.fleetLib);
- const notFound = notFoundVariants(fleetSrc);
- const fleetErrors = enumVariants(fleetSrc, 'Error').map((v) => {
- let surfaces = daemon.map.get(v.name) ?? daemon.other;
- if (surfaces === 'from') surfaces = daemon.guest.join(', ');
- if (notFound.has(v.name)) surfaces = v.name === 'Sdk' ? `${daemon.notFound} (a missing object), else ${surfaces}` : daemon.notFound;
- const message = v.message === '{}' && v.name === 'MissingCredentials' ? dump.config.missing_credentials : v.message;
- return { name: v.name, doc: v.doc, message, surfaces };
- });
- const sdkErrors = enumVariants(read(path.join(SOURCES.sdkDir, 'error.rs')), 'SdkError').map((v) => ({
- name: v.name,
- doc: v.doc,
- message: v.message,
- }));
- for (const e of sdkErrors) if (fleetErrors.some((f) => f.name === e.name)) e.name = `SdkError.${e.name}`;
- const version = read(R('libs', 'cua', 'VERSION')).trim();
- return {
- dump,
- routes,
- ops,
- swagger,
- handle,
- tf,
- tfProvider,
- tfDocs: parseTfDocs(read(path.join(SOURCES.tfDir, 'docs', 'resources', 'pool.md'))),
- tfMapping: JSON.parse(read(path.join(providerDir, 'generate', 'pool_mapping.json'))),
- tfSource,
- tfExample: tfExample(),
- imageSchema: JSON.parse(read(SOURCES.imageSchema)),
- secretRoute: `${secret[1]}{namespace}${secret[2]}`,
- errors: { fleet: fleetErrors, sdk: sdkErrors },
- descriptions: JSON.parse(read(DESCRIPTIONS_FILE)),
- version,
- };
-}
-
-export function renderAll(ctx: Ctx): Map<string, string> {
- const files = new Map<string, string>();
- files.set(path.join(OUT_DIR, 'index.mdx'), renderIndex(ctx));
- for (const def of OBJECTS) files.set(path.join(OUT_DIR, `${def.slug}.mdx`), renderObjectPage(ctx, def));
- files.set(path.join(OUT_DIR, 'terraform.mdx'), renderTerraformPage(ctx));
- files.set(path.join(OUT_DIR, 'errors.mdx'), renderErrorsPage(ctx));
- files.set(
- path.join(OUT_DIR, 'meta.json'),
- metaJson('Reference', ['index', ...OBJECTS.map((d) => d.slug), 'terraform', 'errors'])
- );
- return files;
-}
-
-function main(): void {
- const checkOnly = isCheckMode();
- const ctx = buildContext(loadDump());
- finish('Cua Fleets', syncFiles(renderAll(ctx), checkOnly, [OUT_DIR]), checkOnly, REGENERATE);
-}
-
-if (require.main === module) main();
diff --git a/scripts/docs-generators/headers/cua-sdk/runtime-support.md b/scripts/docs-generators/headers/cua-sdk/runtime-support.md
index bd5a714a4b..fa47690bac 100644
--- a/scripts/docs-generators/headers/cua-sdk/runtime-support.md
+++ b/scripts/docs-generators/headers/cua-sdk/runtime-support.md
@@ -49,7 +49,7 @@ disk, so pass `os_type='windows', kind='vm'` for a Windows containerDisk.
Cloud layers fail with a clear error until Fleet builds images. `cua image build` and `cua image push` build and
publish an image both sides can use. See
-[Build and publish an image](/fleets/guides/images).
+[Choose and build an image](/cua-sdk/guides/images).
## Workloads, ports and sidecars
diff --git a/scripts/docs-generators/runner.ts b/scripts/docs-generators/runner.ts
index 8b988113bb..37e8dcaaa0 100644
--- a/scripts/docs-generators/runner.ts
+++ b/scripts/docs-generators/runner.ts
@@ -391,12 +391,7 @@ function testGeneratorRouting(config: Config): void {
['libs/cua/crates/cua-spaces-contract/src/lib.rs', 'docs/content/docs/spaces/reference/agents.mdx', 'scripts/docs-generators/spaces.ts'],
['cua-cli', 'spaces']
);
- assertSelection(
- config,
- ['libs/fleet/backend/docs/swagger.json', 'docs/content/docs/fleets/reference/pool.mdx', 'scripts/docs-generators/fleet.ts'],
- ['fleet']
- );
- assertSelection(config, ['libs/cua/crates/cua-fleet/src/lib.rs'], ['cua-rust', 'fleet']);
+ assertSelection(config, ['libs/cua/crates/cua-fleet/src/lib.rs'], ['cua-rust']);
assertSelection(config, ['docs/content/docs/cua-cli/guides/mcp-server.mdx'], []);
assertSelection(config, ['docs/content/docs/lume/reference/cli/vms.mdx'], ['lume']);
assertSelection(
diff --git a/scripts/images/image-refs-allowlist.json b/scripts/images/image-refs-allowlist.json
index 6b97825562..d33e1622ee 100644
--- a/scripts/images/image-refs-allowlist.json
+++ b/scripts/images/image-refs-allowlist.json
@@ -24,7 +24,6 @@
"docs/content/docs/cua-sdk/reference/typescript/*",
"docs/content/docs/cua-sdk/reference/protocol/*",
"docs/content/docs/cua-cli/reference/*",
- "docs/content/docs/fleets/reference/*",
"docs/content/docs/lume/reference/*",
"docs/content/docs/spaces/reference/*",
"scripts/docs-generators/cli-specs/*.json",
diff --git a/tests/e2e/cua-sdk/docs/extract.py b/tests/e2e/cua-sdk/docs/extract.py
index 2074264b1d..487245360a 100644
--- a/tests/e2e/cua-sdk/docs/extract.py
+++ b/tests/e2e/cua-sdk/docs/extract.py
@@ -56,11 +56,8 @@ BASELINE = REPO / "docs" / "code-block-baseline.json"
# Guides with self-contained runnable blocks; `--strict` (and the suite's
# test_guides_are_tagged) fails if one loses its tags. The Omarchy noVNC and
# Minecraft flows only have fragments or in-guest shell steps; their behaviour
-# is covered by the SDK scenario tests instead. The Fleets quickstart downloads
-# its example from docs/public/scripts (a pinned, published cua-sandbox).
+# is covered by the SDK scenario tests instead.
GUIDES = [
- "fleets/guides/terraform.mdx",
- "fleets/guides/capacity-and-claims.mdx",
"cua-sdk/guides/agent-frameworks.mdx",
"cua-sdk/guides/images.mdx",
"cua-sdk/reference/sandbox/index.mdx",