Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
docs: 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.mdxnew file mode 100644index 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.mdxindex 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 shThe _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.mdxindex 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 sandboxUse `Sandbox.ephemeral` for scripts, CI, and one-off tasks.diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.jsonindex 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",