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: separate local sandbox procedures from Fleet tasks (#3610)

Francesco Bonaccia98f903caea3
diff --git a/docs/content/docs/cloud-fleets.mdx b/docs/content/docs/cloud-fleets.mdx
index 5f50efec9f..a918228ed0 100644
--- a/docs/content/docs/cloud-fleets.mdx
+++ b/docs/content/docs/cloud-fleets.mdx
@@ -30,6 +30,11 @@ actions through that sandbox act inside the guest. With `local=True`, the SDK
uses a sandbox runtime on your own hardware. See [How sandboxes work](/concepts/how-sandboxes-work)
for the distinction between the host, guest, and control connection.
+The SDK is shared, but setup instructions are not interchangeable. Follow Fleet
+guides for hosted pools and claims. For work on your own hardware, start with
+[Manage local sandbox lifecycle](/how-to-guides/sandbox/manage-local-lifecycle).
+Local image-builder steps do not run when Fleet claims a guest.
+
Fleet manages capacity; the Sandbox SDK acquires and uses a guest. The SDK's
default guest endpoint is computer-server. Cua Driver can control the desktop
where it is installed and targeted, but using it inside a Fleet guest requires
diff --git a/docs/content/docs/concepts/how-fleet-images-work.mdx b/docs/content/docs/concepts/how-fleet-images-work.mdx
index 76770e893b..af7e4e4f0d 100644
--- a/docs/content/docs/concepts/how-fleet-images-work.mdx
+++ b/docs/content/docs/concepts/how-fleet-images-work.mdx
@@ -11,7 +11,7 @@ The public `Image` type is the sandbox API's immutable environment specification
A Fleet image is the guest boot artifact referenced by a pool definition. A pool can keep multiple replicas running from the same artifact, and later workloads claim those replicas. The Fleet image is therefore an input to capacity management and replica compatibility rather than a step in one sandbox's SDK setup sequence.
-The public SDK model is documented in [How sandboxes work](/concepts/how-sandboxes-work#images-as-starting-state-contracts), [Choose and build a sandbox image](/how-to-guides/sandbox/images), and the [Image reference](/reference/sandbox-sdk/image).
+The public SDK model is documented in [How sandboxes work](/concepts/how-sandboxes-work#images-as-starting-state-contracts) and the [Image reference](/reference/sandbox-sdk/image). For hosted image selection, use [Choose a Fleet image](/how-to-guides/sandbox/choose-an-image). [Build a local sandbox image](/how-to-guides/sandbox/images) covers the separate local builder workflow.
## Fleet uses a constrained subset of the SDK image surface
@@ -60,5 +60,5 @@ Changing the referenced image version requires publishing the corresponding arti
## Related pages
- [How sandboxes work](/concepts/how-sandboxes-work)
-- [Choose and build a sandbox image](/how-to-guides/sandbox/images)
+- [Choose a Fleet image](/how-to-guides/sandbox/choose-an-image)
- [Image reference](/reference/sandbox-sdk/image)
diff --git a/docs/content/docs/concepts/how-sandboxes-work.mdx b/docs/content/docs/concepts/how-sandboxes-work.mdx
index 1af5e13f0f..fca17ddb7f 100644
--- a/docs/content/docs/concepts/how-sandboxes-work.mdx
+++ b/docs/content/docs/concepts/how-sandboxes-work.mdx
@@ -7,6 +7,14 @@ A Cua Sandbox is a **full, isolated computer**, not a remote desktop session. In
Those are two complementary halves of the same computer. The code half and the GUI half share one filesystem, one set of processes, and one OS state. The value is that they live in the same place. An agent can click through an app and then run a Python function against the files or process state that app produced. It can also set up state in code and then automate the UI over that state.
+The Sandbox SDK is the shared interface. Local execution starts the guest through
+a runtime on your hardware; Fleet manages hosted capacity in pools, and a claim
+reserves a guest for your workload. They share the sandbox concept, but differ in
+image preparation, credentials, supported operations, and cleanup. Use
+[Cloud Fleets](/cloud-fleets) for the hosted path or
+[Manage local sandbox lifecycle](/how-to-guides/sandbox/manage-local-lifecycle)
+for local setup.
+
For the broader model that combines code, structured tools, and graphical interfaces, read [What is computer use?](/concepts/what-is-computer-use).
## Sandboxes and real machines
@@ -85,7 +93,7 @@ for the published-artifact workflow.
Local mode runs on the developer's hardware. Linux containers use Docker Desktop, macOS VMs use Lume, and VM backends can use QEMU or Hyper-V. Local execution depends on the machine's available CPU, memory, disk, and virtualization support. Select it with `local=True`.
-The sandbox still starts from an `Image`, exposes a code half and a GUI half, and can be ephemeral or persistent. See [Choose and build a sandbox image](/how-to-guides/sandbox/images#how-a-linux-image-runs-locally) for local setup.
+The sandbox still starts from an `Image`, exposes a code half and a GUI half, and can be ephemeral or persistent. See [Build a local sandbox image](/how-to-guides/sandbox/images#how-a-linux-image-runs-locally) for local setup.
## Fleet execution
diff --git a/docs/content/docs/how-to-guides/sandbox/choose-an-image.mdx b/docs/content/docs/how-to-guides/sandbox/choose-an-image.mdx
index 39d98cf38f..5bd8cdb871 100644
--- a/docs/content/docs/how-to-guides/sandbox/choose-an-image.mdx
+++ b/docs/content/docs/how-to-guides/sandbox/choose-an-image.mdx
@@ -1,15 +1,16 @@
---
-title: Choose a sandbox image
-description: Choose between a published Fleet image, local image customization, and preparing a Fleet boot artifact.
+title: Choose a Fleet image
+description: Select a published guest image for a Fleet pool, or decide when to prepare a custom artifact.
---
-Choose an image workflow based on where the sandbox will run and whether a
-published artifact already contains the software you need.
+Use this guide for hosted Fleet pools. Choose a published artifact that contains
+the software and services your workload needs, or prepare a custom artifact
+before creating the pool. For execution on your own hardware, use
+[Build a local sandbox image](/how-to-guides/sandbox/images).
| Your task | Start here | What you get |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| Run a Fleet workload using an existing image | [Choose a published Fleet image](/how-to-guides/sandbox/images#choose-a-published-fleet-image) | A registry artifact reference for a pool. |
-| Add packages, files, or setup commands for local execution | [Choose a local base image](/how-to-guides/sandbox/images#choose-a-base-image) | An image specification whose builder steps run locally. |
+| Run a Fleet workload using an existing image | [Choose a published Fleet image](#choose-a-published-fleet-image) | A registry artifact reference for a pool. |
| Run a Fleet workload that needs a custom guest | [Prepare and reference a Fleet image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image) | A bootable guest disk packaged and published as a containerDisk artifact. |
Before choosing an artifact, check the [OS and image catalog](/reference/sandbox-sdk/os-image-catalog)
@@ -22,3 +23,46 @@ snapshot-derived image inputs. Local builder methods do not publish an artifact
or run during a Fleet claim. See [Sandbox runtime support](/reference/sandbox-sdk/runtime-support#image-customization)
for the versioned contract and [How Fleet images work](/concepts/how-fleet-images-work)
for the published-artifact model.
+
+## Choose a published Fleet image
+
+1. Open the [OS and image catalog](/reference/sandbox-sdk/os-image-catalog) and
+ choose a Fleet VM artifact that matches your guest OS and workload. Check its
+ architecture and evidence limits. Local Docker and Lume entries are separate
+ runtime choices, not built-in Fleet mappings.
+2. Check the artifact's guest services against your client. The Sandbox SDK's
+ default connection expects computer-server on port `8000`; an MCP client needs
+ an image that starts an MCP service. Declaring a port does not install either
+ service. See the [Fleet guest-service contract](/reference/sandbox-sdk/runtime-support#fleet-guest-service-contract).
+3. Use the built-in constructor for a mapped artifact, or copy the exact registry
+ reference into `Image.from_registry()`. Set the guest OS and `kind='vm'`
+ explicitly. Use a digest when you need an identity independent of tag changes.
+4. Follow [Create a sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python) to apply
+ the image and claim a replica. Confirm registry access, guest readiness, and
+ the operation your workload needs before reusing that pool.
+
+For an explicit registry reference, set `FLEET_IMAGE_REF` to the artifact you
+selected, then construct the image specification:
+
+```python
+import os
+from cua_sandbox import Image
+
+image = Image.from_registry(
+ os.environ['FLEET_IMAGE_REF'],
+ os_type='linux',
+ kind='vm',
+)
+```
+
+For a Windows artifact, change `os_type` to `'windows'`; this selects EFI in the
+generated Fleet template. This snippet defines an image without provisioning it.
+For image-specific service configuration, use the catalog's linked recipe.
+
+Windows images do not include a Windows license. Before provisioning one,
+confirm that your own licenses cover your intended use, including applicable
+hosting and virtualization rights. A successful boot is not a licensing check.
+
+If the artifact lacks required software, [prepare and publish a guest image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image)
+before creating the pool. Local SDK builder methods do not publish an artifact
+or run during a Fleet claim.
diff --git a/docs/content/docs/how-to-guides/sandbox/images.mdx b/docs/content/docs/how-to-guides/sandbox/images.mdx
index 7836b0a65e..d1d73c71ff 100644
--- a/docs/content/docs/how-to-guides/sandbox/images.mdx
+++ b/docs/content/docs/how-to-guides/sandbox/images.mdx
@@ -1,18 +1,16 @@
---
-title: Choose and build a sandbox image
-description: Select a sandbox base image and add packages, files, setup commands, ports, and inspection.
+title: Build a local sandbox image
+description: Select a local sandbox base image and add packages, files, setup commands, and ports for execution on your own hardware.
---
import { Callout } from 'fumadocs-ui/components/callout';
-Use an **Image** to define the OS and software environment for a sandbox before you start it.
+This guide uses the Sandbox SDK on your own hardware with `local=True`. Use an
+**Image** to define the guest OS and setup steps before starting a local sandbox.
+Start with [Choose a base image](#choose-a-base-image).
-Start with [Choose a sandbox image](/how-to-guides/sandbox/choose-an-image) if you
-need to decide between using a published Fleet artifact, customizing a local
-image, or publishing a Fleet artifact.
-
-For Fleet, [choose a published image](#choose-a-published-fleet-image). For local
-execution, [choose a base image](#choose-a-base-image) and add the setup steps below.
+For hosted execution, follow [Choose a Fleet image](/how-to-guides/sandbox/choose-an-image).
+The local builder steps below do not publish a Fleet artifact or run during a claim.
<Callout type="warn">
**SDK builder customization is local-only in `cua-sandbox` 0.4.3.** `apt_install()`,
@@ -26,46 +24,9 @@ execution, [choose a base image](#choose-a-base-image) and add the setup steps b
## Choose a published Fleet image
-1. Open the [OS and image catalog](/reference/sandbox-sdk/os-image-catalog) and
- choose a Fleet VM artifact that matches your guest OS and workload. Check its
- architecture and evidence limits. Local Docker and Lume entries are separate
- runtime choices, not built-in Fleet mappings.
-2. Check the artifact's guest services against your client. The Sandbox SDK's
- default connection expects computer-server on port `8000`; an MCP client needs
- an image that starts an MCP service. Declaring a port does not install either
- service. See the [Fleet guest-service contract](/reference/sandbox-sdk/runtime-support#fleet-guest-service-contract).
-3. Use the built-in constructor for a mapped artifact, or copy the exact registry
- reference into `Image.from_registry()`. Set the guest OS and `kind='vm'`
- explicitly. Use a digest when you need an identity independent of tag changes.
-4. Follow [Create a sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python) to apply
- the image and claim a replica. Confirm registry access, guest readiness, and
- the operation your workload needs before reusing that pool.
-
-For an explicit registry reference, set `FLEET_IMAGE_REF` to the artifact you
-selected, then construct the image specification:
-
-```python
-import os
-from cua_sandbox import Image
-
-image = Image.from_registry(
- os.environ['FLEET_IMAGE_REF'],
- os_type='linux',
- kind='vm',
-)
-```
-
-For a Windows artifact, change `os_type` to `'windows'`; this selects EFI in the
-generated Fleet template. This snippet defines an image without provisioning it.
-For image-specific service configuration, use the catalogue's linked recipe.
-
-Windows images do not include a Windows license. Before provisioning one,
-confirm that your own licenses cover your intended use, including applicable
-hosting and virtualization rights. A successful boot is not a licensing check.
-
-If the artifact lacks required software, [prepare and publish a guest image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image)
-before creating the pool. The local builder examples below do not publish a
-Fleet artifact or run during a Fleet claim.
+The hosted procedure is now in [Choose a Fleet image](/how-to-guides/sandbox/choose-an-image#choose-a-published-fleet-image).
+Use that guide for published artifacts, guest-service requirements, and Windows
+licensing requirements. Continue below only for local execution.
## Choose a base image
@@ -87,13 +48,8 @@ Image.android() # Android 14
```
Choose a constructor using the [OS and runtime table](/reference/sandbox-sdk/runtime-support#operating-systems-and-image-kinds).
-The built-in Ubuntu 24.04 and Windows Server 2022 VMs map to registry artifacts for
-Fleet; the other built-in inputs do not. A constructor returning an `Image` does
-not verify that its guest can boot on your host or Fleet deployment.
-
-For Windows, released 0.4.3 selects EFI in the Fleet template. See
-[Windows firmware](/reference/sandbox-sdk/runtime-support#windows-firmware) before
-diagnosing an unready Windows guest as a BIOS mismatch.
+A constructor returning an `Image` does not verify that its guest can boot on
+your host. Check local runtime requirements before selecting it.
If a local Docker image times out on readiness, check the guest server's listening
address. An earlier `trycua/cua-xfce:latest` recipe reported the server bound to
diff --git a/docs/content/docs/how-to-guides/sandbox/interactive-shell.mdx b/docs/content/docs/how-to-guides/sandbox/interactive-shell.mdx
index f4b0e6d8d6..e74ccb9a67 100644
--- a/docs/content/docs/how-to-guides/sandbox/interactive-shell.mdx
+++ b/docs/content/docs/how-to-guides/sandbox/interactive-shell.mdx
@@ -1,13 +1,13 @@
---
-title: Open an interactive shell in a sandbox
-description: Open an interactive PTY session inside the code half of a sandbox from the CLI or Python SDK.
+title: Open an interactive shell in a local sandbox
+description: Open an interactive PTY session in a local sandbox from the CLI or Python SDK.
---
-A **Cua Sandbox** is a full isolated computer where an agent can run code and drive the GUI. Use `cua do shell` or the Sandbox SDK terminal API to open an interactive PTY session in the code half of that sandbox, similar to SSH but without network setup. The same sandbox is also driven through the GUI via computer-use with screenshots, clicks, and typing. Because both share one machine, you can run code and automate the UI against the same filesystem and state.
+Use `cua do shell` or the Sandbox SDK terminal API to open an interactive PTY session in a local sandbox, similar to SSH but without network setup. The same sandbox is also driven through the GUI via computer-use with screenshots, clicks, and typing. Because both share one machine, you can run code and automate the UI against the same filesystem and state.
## From the CLI
-Switch to the sandbox target first.
+Switch to the target first. The Docker target opens a shell in the selected container. The host target runs directly on your host computer; it is not an isolated guest.
```bash
# Switch to a target first
@@ -30,7 +30,7 @@ The shell is fully interactive: arrow keys, tab completion, and Ctrl+C work. Whe
## From the Python SDK
-Create a sandbox, open a PTY session with `sb.terminal.create`, send input as text, read session info, then close the session.
+Create a local sandbox with `local=True`, open a PTY session with `sb.terminal.create`, send input as text, read session info, then close the session.
```python
from cua import Sandbox, Image
diff --git a/docs/content/docs/how-to-guides/sandbox/scale-out.mdx b/docs/content/docs/how-to-guides/sandbox/scale-out.mdx
index a49f4745b7..5911606bf8 100644
--- a/docs/content/docs/how-to-guides/sandbox/scale-out.mdx
+++ b/docs/content/docs/how-to-guides/sandbox/scale-out.mdx
@@ -1,11 +1,13 @@
---
-title: Run sandboxes in parallel
-description: Run many sandbox jobs at once, limit concurrency, and handle failures.
+title: Run local sandboxes in parallel
+description: Run many local sandbox jobs at once, limit concurrency, and handle failures.
---
import { Callout } from 'fumadocs-ui/components/callout';
-Because `Sandbox.ephemeral` and `Sandbox.create` are async, you can **run many sandboxes at the same time** using `asyncio`.
+This guide runs local sandboxes with `local=True`. Because `Sandbox.ephemeral` and `Sandbox.create` are async, you can **run many local sandboxes at the same time** using `asyncio`.
+
+For hosted Fleet capacity, follow [Create a sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python) to create a pool and claim sandboxes for your tasks.
<Callout type="info">
Every local sandbox consumes host CPU, memory, and disk. Start with low concurrency and increase it only after observing host resource use.
diff --git a/docs/content/docs/how-to-guides/sandbox/secrets.mdx b/docs/content/docs/how-to-guides/sandbox/secrets.mdx
index c25231b96d..ac845a5327 100644
--- a/docs/content/docs/how-to-guides/sandbox/secrets.mdx
+++ b/docs/content/docs/how-to-guides/sandbox/secrets.mdx
@@ -7,7 +7,7 @@ import { Callout } from 'fumadocs-ui/components/callout';
Pass task-specific credentials from the host into a sandbox at runtime. Keep secrets out of image specifications, build commands, and copied application files.
-These examples use a connected Linux sandbox named `sb` with a POSIX shell and Python 3. Put your application at `/app/main.py` before running them. Use credentials with only the permissions and lifetime the task needs.
+The runtime examples apply to both local and hosted Fleet guests. They use a connected Linux sandbox named `sb` with a POSIX shell and Python 3. Put your application at `/app/main.py` before running them. Use credentials with only the permissions and lifetime the task needs.
## Inject secrets at runtime
@@ -42,7 +42,7 @@ The assignments apply to the application and its child processes. They do not co
## Keep image configuration non-sensitive
-Use `Image.env()` for non-sensitive config, **not for secrets**.
+For local image builds, use `Image.env()` for non-sensitive config, **not for secrets**. The following builder example is local-only. For hosted Fleet, prepare configuration in the [prebuilt guest artifact](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image) before publishing it.
```python
from cua_sandbox import Image
diff --git a/docs/content/docs/how-to-guides/sandbox/tunneling.mdx b/docs/content/docs/how-to-guides/sandbox/tunneling.mdx
index 69c890a8f4..741b934845 100644
--- a/docs/content/docs/how-to-guides/sandbox/tunneling.mdx
+++ b/docs/content/docs/how-to-guides/sandbox/tunneling.mdx
@@ -1,6 +1,6 @@
---
-title: Forward a port from a sandbox
-description: Reach a sandbox service through a local startup mapping, a Fleet service request, or a supported tunnel transport.
+title: Connect to a sandbox service
+description: Reach a sandbox service through a Fleet service request, a local startup mapping, or a supported tunnel transport.
---
Choose the connection method for your sandbox's transport. In `cua-sandbox`
@@ -9,10 +9,28 @@ Choose the connection method for your sandbox's transport. In `cua-sandbox`
[Sandbox runtime support](/reference/sandbox-sdk/runtime-support#ports-and-transports)
for the versioned transport contract.
+## Request a named Fleet service
+
+For a hosted Fleet guest, configure [Fleet pool credentials](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials)
+and use a pool whose guest starts the desired service. Within the claimed
+sandbox's context, send an authenticated request by service name:
+
+```python
+response = await sb.services.request('port-3000', method='GET', path='/healthz')
+response.raise_for_status()
+print(response.text)
+```
+
+An image's `.expose(3000)` declaration creates the `port-3000` service in the
+default pool template. It does not start an application on that port or create
+a localhost listener. See [Prepare and reference a Fleet image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image)
+for the complete image and claim workflow. External clients need the Fleet
+service URL and authentication; an endpoint URL is not anonymous access.
+
## Expose a local QEMU service at startup
-Declare the port on the image before starting a bare-metal QEMU VM, then read the
-host mapping from `sb.exposed_ports`. This example requires QEMU, a compatible
+For a local sandbox, declare the port on the image before starting a bare-metal
+QEMU VM, then read the host mapping from `sb.exposed_ports`. This example requires QEMU, a compatible
host, `cua==0.1.6`, and `httpx`:
```python
@@ -54,28 +72,10 @@ For multiple ports, chain declarations such as
`Image.linux().expose(8080).expose(9222)` and read each guest port's entry from
`sb.exposed_ports` after startup.
-## Request a named Fleet service
-
-Configure [Fleet pool credentials](/reference/cua-cli/authentication#fleet-pools-need-their-own-credentials)
-and use a pool whose guest starts the desired service. Within the claimed
-sandbox's context, send an authenticated request by service name:
-
-```python
-response = await sb.services.request('port-3000', method='GET', path='/healthz')
-response.raise_for_status()
-print(response.text)
-```
-
-An image's `.expose(3000)` declaration creates the `port-3000` service in the
-default pool template. It does not start an application on that port or create
-a localhost listener. See [Prepare and reference a Fleet image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image)
-for the complete image and claim workflow. External clients need the Fleet
-service URL and authentication; an endpoint URL is not anonymous access.
-
## Forward through SSH or ADB
-For an existing sandbox connected through `SSHTransport` or `ADBTransport`, the
-tunnel helper creates a localhost forwarding endpoint. Start the guest service
+This section applies only to an existing sandbox connected through
+`SSHTransport` or `ADBTransport`. The tunnel helper creates a localhost forwarding endpoint. Start the guest service
first, then keep its tunnel open for as long as the client needs it:
```python
diff --git a/docs/content/docs/reference/sandbox-sdk/index.mdx b/docs/content/docs/reference/sandbox-sdk/index.mdx
index fbf38435f7..80976cc15c 100644
--- a/docs/content/docs/reference/sandbox-sdk/index.mdx
+++ b/docs/content/docs/reference/sandbox-sdk/index.mdx
@@ -3,6 +3,12 @@ title: Sandbox SDK reference
description: Packages, configuration, and Sandbox lifecycle APIs for Python and TypeScript.
---
+The Python Sandbox SDK supports local execution and hosted Fleet pools through
+one API. Backend support differs even when method names are shared. Use
+[Sandbox runtime support](/reference/sandbox-sdk/runtime-support) for local/Fleet
+image and transport differences, and [Sandbox lifecycle](/concepts/sandbox-lifecycle)
+for connection, claim, and capacity ownership.
+
## Packages
This reference describes the published `cua-sandbox` 0.4.3 Python package and
diff --git a/docs/content/docs/tutorials/your-first-cloud-fleet.mdx b/docs/content/docs/tutorials/your-first-cloud-fleet.mdx
index 25b41362aa..6618f1d90e 100644
--- a/docs/content/docs/tutorials/your-first-cloud-fleet.mdx
+++ b/docs/content/docs/tutorials/your-first-cloud-fleet.mdx
@@ -270,5 +270,5 @@ claim releases the sandbox, and namespace deletion requests resource removal.
- [Create a reusable sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python)
- [Configure a sandbox pool with Terraform](/how-to-guides/sandbox/configure-pool-with-terraform)
- [Expire pools and claims automatically](/how-to-guides/sandbox/expire-pools-and-claims)
-- [Choose a sandbox image](/how-to-guides/sandbox/choose-an-image)
+- [Choose a Fleet image](/how-to-guides/sandbox/choose-an-image)
- [Sandbox SDK API reference](/reference/sandbox-sdk)
diff --git a/docs/scripts/tests/test_local_fleet_task_boundaries.py b/docs/scripts/tests/test_local_fleet_task_boundaries.py
new file mode 100644
index 0000000000..96802ce235
--- /dev/null
+++ b/docs/scripts/tests/test_local_fleet_task_boundaries.py
@@ -0,0 +1,62 @@
+"""Keep local setup out of the hosted image-selection procedure."""
+
+from pathlib import Path
+import re
+import unittest
+
+
+DOCS = Path(__file__).resolve().parents[2] / "content" / "docs"
+
+
+def page(slug: str) -> str:
+ return (DOCS / f"{slug}.mdx").read_text()
+
+
+class LocalFleetTaskBoundariesTests(unittest.TestCase):
+ def test_local_guides_identify_execution_scope(self):
+ for slug in ("images", "manage-local-lifecycle", "interactive-shell", "scale-out"):
+ with self.subTest(slug=slug):
+ text = page(f"how-to-guides/sandbox/{slug}")
+ title = re.search(r"^title: (.+)$", text, re.MULTILINE)
+ self.assertIsNotNone(title)
+ self.assertIn("local", title.group(1).lower())
+
+ def test_fleet_selection_contains_no_local_provisioning(self):
+ text = page("how-to-guides/sandbox/choose-an-image")
+ self.assertIn("## Choose a published Fleet image", text)
+ self.assertIn("Image.from_registry(", text)
+ self.assertIn("Windows images do not include a Windows license", text)
+ for block in re.findall(r"```python[^\n]*\n(.*?)```", text, re.DOTALL):
+ self.assertNotIn("local=True", block)
+ self.assertNotIn(".apt_install(", block)
+ self.assertNotIn(".run(", block)
+
+ def test_old_image_selection_anchor_forwards_to_hosted_guide(self):
+ text = page("how-to-guides/sandbox/images")
+ section = text.split("## Choose a published Fleet image\n", 1)[1].split("\n## ", 1)[0]
+ self.assertIn(
+ "/how-to-guides/sandbox/choose-an-image#choose-a-published-fleet-image", section
+ )
+ self.assertNotIn("```", section)
+ self.assertIn("## Choose a base image", text)
+ destination = page("how-to-guides/sandbox/choose-an-image")
+ self.assertIn("## Choose a published Fleet image", destination)
+
+ def test_hosted_next_steps_name_the_fleet_image_guide(self):
+ for slug in ("concepts/how-fleet-images-work", "tutorials/your-first-cloud-fleet"):
+ with self.subTest(slug=slug):
+ text = page(slug)
+ self.assertIn(
+ "[Choose a Fleet image](/how-to-guides/sandbox/choose-an-image)", text
+ )
+ self.assertNotIn("[Choose and build a sandbox image]", text)
+
+ def test_shared_reference_exposes_backend_limits(self):
+ text = page("reference/sandbox-sdk/index")
+ self.assertIn("one API", text)
+ self.assertIn("/reference/sandbox-sdk/runtime-support", text)
+ self.assertIn("/concepts/sandbox-lifecycle", text)
+
+
+if __name__ == "__main__":
+ unittest.main()