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: add Cloud Fleets overview and clarify target boundaries (#3589)

Francesco Bonaccie45d84f4239d
diff --git a/docs/content/docs/cloud-fleets.mdx b/docs/content/docs/cloud-fleets.mdx
new file mode 100644
index 0000000000..5f50efec9f
--- /dev/null
+++ b/docs/content/docs/cloud-fleets.mdx
@@ -0,0 +1,47 @@
+---
+title: Cloud Fleets
+description: Find tutorials, guides, explanations, and reference for managed cloud sandboxes.
+---
+
+Cloud Fleets provisions and manages sandbox capacity for your workloads. The
+Sandbox SDK represents a Fleet as a `Pool`; your code claims a sandbox from the
+pool and uses that guest computer.
+
+Start with [Your first Cloud Fleet](/tutorials/your-first-cloud-fleet) to provision
+a pool, run a command, save a screenshot, and clean up the cloud resources.
+
+## Find the right page
+
+Choose a page based on what you want to do:
+
+| Your goal | Start here |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Learn through a first working example | [Your first Cloud Fleet](/tutorials/your-first-cloud-fleet) |
+| Create reusable capacity | [Create a sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python) or [Configure a sandbox pool with Terraform](/how-to-guides/sandbox/configure-pool-with-terraform) |
+| Control resource lifetime | [Expire pools and claims automatically](/how-to-guides/sandbox/expire-pools-and-claims) |
+| Prepare a guest environment | [Prepare and reference a Fleet image](/how-to-guides/sandbox/prepare-and-reference-a-fleet-image) |
+| Understand the model | [How sandboxes work](/concepts/how-sandboxes-work) and [How Fleet images work](/concepts/how-fleet-images-work) |
+| Look up APIs and limits | [Sandbox SDK reference](/reference/sandbox-sdk), [Pool reference](/reference/sandbox-sdk/pool), and [Sandbox runtime support](/reference/sandbox-sdk/runtime-support) |
+
+## Which computer runs the work?
+
+With Fleet, the SDK connects to a claimed cloud guest. Shell commands and GUI
+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.
+
+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
+a compatible image and a validated connection path. Choosing a Fleet image does
+not by itself establish Driver integration. Check the [image and runtime limits](/reference/sandbox-sdk/runtime-support)
+before selecting your environment.
+
+## Claims and capacity have separate lifetimes
+
+Exiting a `pool.claim()` context releases the claim. The pool can still retain
+warm sandboxes, and cloud resources can incur usage charges after your workload
+finishes. The hosted tutorial includes pool deletion; reusable pools need an
+explicit cleanup or expiry policy. See [Pool lifecycle](/reference/sandbox-sdk/pool)
+for connection and release semantics, and [Expire pools and claims automatically](/how-to-guides/sandbox/expire-pools-and-claims)
+for deadlines and their effect on active work.
diff --git a/docs/content/docs/concepts/how-sandboxes-work.mdx b/docs/content/docs/concepts/how-sandboxes-work.mdx
index 1ece5cc8d9..fba13b73fe 100644
--- a/docs/content/docs/concepts/how-sandboxes-work.mdx
+++ b/docs/content/docs/concepts/how-sandboxes-work.mdx
@@ -11,9 +11,16 @@ For the broader model that combines code, structured tools, and graphical interf
## Sandboxes and real machines
-Cua Driver operates a real machine you already have. It can observe and control that machine, so its actions happen in the same desktop environment you use.
+Cua Driver observes and controls the desktop where it is installed and targeted.
+That can be your existing computer or a guest with a compatible installation and
+connection path. Running Driver on your host does not automatically target a
+sandbox guest.
-A sandbox is different. It is a disposable machine created for a task. It starts from a known state, accumulates state only while it lives, and can be deleted without consequence. Actions inside a sandbox affect only that sandbox. They do not move the host mouse, change host files, or touch other sandboxes.
+A sandbox is an isolated computer created for a task. It starts from an image and
+accumulates its own state. Deleting it discards that state, so save any results
+you need first. Code and GUI actions through the sandbox connection target the
+guest. Explicitly shared files and exposed services remain connections to the
+outside world.
This isolation is what makes a sandbox useful for repeatable agent work. The agent gets a whole computer, but the effects are contained within that computer.
@@ -23,6 +30,13 @@ The _code half_ is how an agent runs programs inside the sandbox. It includes sh
The _GUI half_ is how an agent uses the sandbox like a desktop computer. It can observe the screen through screenshots and the accessibility tree, then act through clicks, typing, scrolling, keypresses, and other input events.
+The Sandbox SDK's default Fleet connection uses the guest's computer-server
+endpoint. Fleet provisions and manages the capacity; the SDK acquires a guest and
+connects to its service. Using Cua Driver in that guest requires its own
+compatible installation and validated integration; it does not follow merely
+from creating a pool. See [How Fleet images work](/concepts/how-fleet-images-work)
+for the default guest service contract.
+
Because both halves are interfaces to the same machine, they can be mixed within one task. A shell command can create a file that is opened in the GUI. A GUI workflow can download data that is then inspected with Python. A PTY session can start a server, and the GUI half can open a browser against it. The important point is that all of these actions share the same filesystem and OS state.
## Containers and full VMs
@@ -43,6 +57,11 @@ This separation makes environments reproducible. The `Image` describes what a fr
## Lifecycle patterns
+The patterns below describe local sandbox ownership. Fleet pools and claims add
+a separate capacity lifetime: releasing a claim does not delete its pool or
+remove the pool's desired warm capacity. [Cloud Fleets](/cloud-fleets) links the
+hosted workflow and resource cleanup guides.
+
Sandbox lifetime is separate from agent connection lifetime. An ephemeral sandbox exists for one block of work and is destroyed at the end. This fits CI jobs, tests, and one-shot tasks where the state has no value afterward.
A persistent or named sandbox is created once, identified by name, and can survive process exits. A later process can reconnect to the same sandbox and continue from the state it already has.
diff --git a/docs/content/docs/concepts/sandbox-lifecycle.mdx b/docs/content/docs/concepts/sandbox-lifecycle.mdx
index 7ef348a87a..46accb451d 100644
--- a/docs/content/docs/concepts/sandbox-lifecycle.mdx
+++ b/docs/content/docs/concepts/sandbox-lifecycle.mdx
@@ -12,6 +12,13 @@ release behavior differs from deleting a local VM. See [Your first Cloud Fleet](
for a pool-and-claim workflow and [Sandbox runtime support](/reference/sandbox-sdk/runtime-support)
for image and transport limits.
+On Fleet, `disconnect()` drops the connection without releasing the claim.
+Exiting a `pool.claim()` context releases the claim, but the pool can keep warm
+capacity available and incur cloud usage charges. Deleting the pool is a
+separate operation that removes its capacity and state. See the [Pool reference](/reference/sandbox-sdk/pool)
+for exact ownership and release behavior, and [Expire pools and claims automatically](/how-to-guides/sandbox/expire-pools-and-claims)
+for cleanup deadlines.
+
## Create and auto-destroy a sandbox
Use `Sandbox.ephemeral` for scripts, CI, and one-off tasks.
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index aac0eb6054..febf868a81 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -3,6 +3,7 @@
"root": true,
"pages": [
"index",
+ "cloud-fleets",
"---Learn---",
"tutorials",
"concepts",