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: run Cursor Cloud Agents on Cua Fleet
Francesco Bonacci22b727430a16
diff --git a/docs/content/docs/how-to-guides/sandbox/meta.json b/docs/content/docs/how-to-guides/sandbox/meta.jsonindex fcae338297..1bd0df9716 100644--- a/docs/content/docs/how-to-guides/sandbox/meta.json+++ b/docs/content/docs/how-to-guides/sandbox/meta.json@@ -4,6 +4,7 @@"configure-pool-with-terraform","create-pool-with-python","create-pool-with-typescript",+ "run-cursor-cloud-agent-on-fleet","expire-pools-and-claims","run-openclaw-on-cloud-fleet","run-omarchy-on-cloud-fleet",diff --git a/docs/content/docs/how-to-guides/sandbox/run-cursor-cloud-agent-on-fleet.mdx b/docs/content/docs/how-to-guides/sandbox/run-cursor-cloud-agent-on-fleet.mdxnew file mode 100644index 0000000000..93f1ee8d08--- /dev/null+++ b/docs/content/docs/how-to-guides/sandbox/run-cursor-cloud-agent-on-fleet.mdx@@ -0,0 +1,321 @@+---+title: Run a Cursor Cloud Agent worker on Cua Cloud Fleet+description: Start a Cursor self-hosted Team Pool worker inside a claimed Cua Cloud Fleet Linux desktop.+---++import { Callout } from 'fumadocs-ui/components/callout';++Use this guide to run one Cursor self-hosted Cloud Agent worker inside a Cua+Cloud Fleet VM. A local Python controller creates a reusable Cua pool, claims a+VM, starts the Cursor worker in that VM, and keeps the claim alive until you+stop the controller.++```text+Cursor Cloud Agent control plane+ |+ | outbound worker connection+ v+Cursor worker in a claimed Cua Fleet VM+ |+ +-- repository checkout and terminal tools+ +-- XFCE/X11 desktop and browser+ +-- private services reachable from the VM+```++<Callout type="warn">+ This is a manual integration path, not a built-in Cursor provider. The controller must remain+ running because the Cua claim owns the VM used by the Cursor worker. Scaling Cua capacity from+ Cursor's pending-request queue requires an additional controller and is not covered here.+</Callout>++## Prerequisites++You need:++- Python `>=3.11,<3.14` and [`uv`](https://docs.astral.sh/uv/);+- Cua Fleet credentials that can create pools and claims;+- a Cursor Enterprise plan with Self-Hosted Agents enabled;+- a Cursor service-account API key for Team Pool workers; and+- a globally unique, lowercase DNS-label name for the Cua pool.++This guide uses the public Cua Ubuntu 24.04 desktop image:++```text+public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04@sha256:c1e601dbb748fdc467c663136f7592e308a91a3c19c309b75261544432826a57+```++The image provides a glibc-based Linux VM, an XFCE/X11 desktop, and the Cua+computer server on port `8000`. The Cursor CLI and worker are third-party+software installed at runtime from Cursor's official installer.++## Configure credentials and names++Authenticate to Cua Fleet with an access token:++```bash+export FLEETS_TOKEN="<your-cua-access-token>"+```++Or use Cua OAuth client credentials:++```bash+export CUA_CLIENT_ID="<your-cua-client-id>"+export CUA_CLIENT_SECRET="<your-cua-client-secret>"+```++Set the Cua pool name, Cursor Team Pool name, and Cursor service-account key:++```bash+export CUA_POOL_NAME="<globally-unique-cua-pool-name>"+export CURSOR_WORKER_POOL_NAME="cua-linux"+export CURSOR_API_KEY="<cursor-service-account-api-key>"+```++The two pool names identify different resources:++| Variable | Meaning |+| --- | --- |+| `CUA_POOL_NAME` | The Cua Fleet pool that supplies VMs |+| `CURSOR_WORKER_POOL_NAME` | The Cursor Team Pool that receives Cloud Agent requests |++Keep both providers' credentials in environment variables or a secret manager.+Do not store them in an image definition or commit them to source control.++## Start the Fleet-backed worker++Save this script as `run_cursor_worker.py`:++```python title="run_cursor_worker.py"+# /// script+# requires-python = ">=3.11,<3.14"+# dependencies = [+# "cua-sandbox",+# ]+# ///++import asyncio+import os+import shlex++from cua_sandbox import Image, Pool+++IMAGE = (+ "public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04"+ "@sha256:c1e601dbb748fdc467c663136f7592e308a91a3c19c309b75261544432826a57"+)+CUA_POOL_NAME = os.environ["CUA_POOL_NAME"]+CURSOR_POOL_NAME = os.environ["CURSOR_WORKER_POOL_NAME"]+CURSOR_API_KEY = os.environ["CURSOR_API_KEY"]+++async def checked(sandbox, command: str, timeout: int = 300) -> str:+ result = await sandbox.shell.run(command, timeout=timeout)+ if not result.success:+ raise RuntimeError(f"{command}\n{result.stderr}")+ return result.stdout.strip()+++async def main() -> None:+ pool = await Pool.apply(+ Image.from_registry(IMAGE, os_type="linux", kind="vm"),+ name=CUA_POOL_NAME,+ replicas=1,+ cpu=4,+ memory_mb=8192,+ services={"server": 8000},+ )++ async with pool.claim(service="server", time_to_start=1800) as sandbox:+ print(f"Cua pool: {sandbox.pool_name}")+ print(f"Cua claim: {sandbox.claim_name}")+ print(f"Sandbox: {sandbox.name}")++ await checked(sandbox, "curl -fsSL https://cursor.com/install -o /tmp/cursor-install.sh")+ await checked(sandbox, "bash /tmp/cursor-install.sh")+ await checked(sandbox, "test -x /root/.local/bin/agent")++ await checked(+ sandbox,+ "mkdir -p /root/.config /root/cursor-workspaces/default",+ )++ # Write the credential through the file API so it is not interpolated+ # into a shell command or printed by the controller.+ env_file = (+ f"CURSOR_API_KEY={shlex.quote(CURSOR_API_KEY)}\n"+ f"CURSOR_WORKER_POOL_NAME={shlex.quote(CURSOR_POOL_NAME)}\n"+ )+ await sandbox.files.write_bytes(+ "/root/.config/cursor-worker.env",+ env_file.encode(),+ )+ await checked(+ sandbox,+ "chmod 600 /root/.config/cursor-worker.env",+ )++ command = """bash -lc '+set -a+. /root/.config/cursor-worker.env+set +a+export PATH=/root/.local/bin:$PATH+exec agent worker \\+ --pool "$CURSOR_WORKER_POOL_NAME" \\+ --worker-dir /root/cursor-workspaces/default \\+ --clone-git-repos \\+ start > /root/cursor-worker.log 2>&1+'"""+ worker = await sandbox.shell.run(command, background=True)+ if not worker.success:+ raise RuntimeError(worker.stderr)++ try:+ print(f"Cursor worker process: {worker.stdout or 'started'}")+ print("The Cua claim is active. Press Ctrl-C to release it.")++ while True:+ await asyncio.sleep(15)+ status = await sandbox.shell.run(+ "pgrep -af '[a]gent worker'",+ timeout=15,+ )+ if not status.success:+ raise RuntimeError(+ "Cursor worker exited; inspect /root/cursor-worker.log"+ )+ finally:+ await sandbox.shell.run("pkill -f '[a]gent worker' || true")+ await sandbox.shell.run("rm -f /root/.config/cursor-worker.env")+++try:+ asyncio.run(main())+except KeyboardInterrupt:+ print("Releasing the Cua claim; the reusable pool remains available")+```++Run the controller:++```bash+uv run run_cursor_worker.py+```++The first run can take several minutes while Fleet provisions the VM. The+script then installs the Cursor CLI, starts an any-repository Team Pool worker,+and checks every 15 seconds that the worker process remains present.++The `--clone-git-repos` option lets Cursor prepare the assigned repository in+the otherwise empty worker directory. Use this option only for a named+any-repository Team Pool, as described in Cursor's Team Pools documentation.++<Callout type="info">+ The script keeps the Cua pool after you stop it. Later runs can claim its warm capacity without+ rebuilding the pool, but the runtime Cursor CLI installation is not part of the immutable base+ image. For repeated production use, publish a private worker image with a pinned Cursor CLI and+ use that image digest in `Image.from_registry()`.+</Callout>++## Verify the worker++In the Cursor dashboard, open **Cloud Agents → Self-Hosted Agents** and confirm+that an idle worker appears in the Team Pool named by+`CURSOR_WORKER_POOL_NAME`.++Start a Cloud Agent run and select that Team Pool. Ask the agent to perform a+small, reversible check, such as:++```text+Report the operating system, current working directory, and git remote. Do not edit files.+```++Confirm that:++1. Cursor assigns the run to the registered worker.+2. The reported operating system is Linux.+3. The repository is cloned under the worker's workspace.+4. The local controller continues to report a live claim.++If you intend to use graphical tools, add Cursor's `--computer-use` worker+option and follow Cursor's Linux computer-use dependency and display checks.+The Cua image already provides an X11 desktop, but Cursor's computer-use helper+is separate from Cua Driver and must pass Cursor's own preflight.++## Stop and clean up++Press `Ctrl-C` in the local controller. The script stops the worker and removes+its credential file before exiting the claim context. Exiting the context then+releases the claim. The Cua pool and its warm replica remain for the next run.++Delete the pool only when you no longer need it. Add the following after the+claim context, or use a separate cleanup script that resolves the same named+pool:++```python+await pool.delete()+```++Deleting the pool removes its warm capacity and same-named Fleet namespace.++## Production hardening++Before using this integration for production workloads:++- build and pin a private worker image instead of downloading the CLI at each start;+- run the worker as a dedicated non-root user;+- restrict outbound access to the endpoints required by Cursor and your source provider;+- decide whether Cursor artifact uploads are allowed by your data-handling policy;+- prevent secrets from appearing in terminal output, screenshots, diffs, and artifacts;+- set claim and pool TTLs appropriate for abandoned-controller recovery;+- collect worker logs without recording API keys or repository contents; and+- test claim loss, worker failure, cancellation, and controller restart behavior.++Cursor documents that the worker sends agent-required content to Cursor,+including file contents, terminal output, diffs, screenshots, local MCP+results, and routing metadata. Cursor also documents that Cloud Agent artifacts+may be uploaded to Cursor-managed storage. Running the worker on Cua Fleet+keeps execution in the Fleet VM; it does not make the Cursor agent loop or its+data plane self-hosted.++## Understand the scaling boundary++Cursor and Cua each use a pool, but at different layers:++```text+Cursor Team Pool pending request+ |+ | needs an idle Cursor worker+ v+integration controller+ |+ | creates and holds a Cua claim+ v+Cua Fleet pool -> VM -> Cursor worker process+```++The script in this guide maintains one warm Cua VM and one Cursor worker. A+production autoscaler must observe Cursor pending requests, create or release+Cua claims, start exactly one Team Pool worker per claimed VM, and reconcile+both systems after failures. Do not configure independent autoscalers on both+sides without defining ownership; they can otherwise disagree about desired+capacity or leave workers and claims orphaned.++## Troubleshooting++| Symptom | Check |+| --- | --- |+| No worker appears in Cursor | Confirm Self-Hosted Agents is enabled and `CURSOR_API_KEY` belongs to a Cursor service account |+| Worker exits immediately | Run Cursor's `agent worker ... debug --json` command in the claimed VM and inspect the result |+| Repository is not cloned | Confirm the worker uses a named pool and `--clone-git-repos`, and that Cursor can access the source repository |+| Fleet claim never becomes ready | Verify Cua credentials, pool-name uniqueness, image access, and the `server` service on port `8000` |+| Agent cannot reach an internal service | Test DNS, routing, and outbound policy from inside the Fleet VM |+| Cursor shows no screenshots or artifacts | Review Cursor's required artifact-storage endpoint and your outbound network policy |+| Controller stops and the worker disappears | Expected: the controller owns the Cua claim; run it under a supervised service for persistent use |++## Related documentation++- [Create a sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python)+- [Pass secrets into a sandbox](/how-to-guides/sandbox/secrets)+- [Run sandboxes in parallel](/how-to-guides/sandbox/scale-out)+- [Cursor Self-Hosted Machines](https://cursor.com/docs/cloud-agent/self-hosted)+- [Cursor Team Pools](https://cursor.com/docs/cloud-agent/self-hosted/pool)diff --git a/docs/cursor-self-hosted-cloud-agents-architecture-note.md b/docs/cursor-self-hosted-cloud-agents-architecture-note.mdnew file mode 100644index 0000000000..a1e57ab310--- /dev/null+++ b/docs/cursor-self-hosted-cloud-agents-architecture-note.md@@ -0,0 +1,188 @@+# Cursor self-hosted cloud agents: architecture and implications for Cua++**Status:** Product and architecture note++**Date:** 2026-09-02++**Source date:** Cursor announcement observed 2026-09-02; Cursor launch post published 2026-03-25++## Executive summary++Cursor now lets customers run cloud-agent workers on infrastructure they control while Cursor retains the agent experience, orchestration, and model access. The customer-hosted workers can reach private code, caches, dependencies, build systems, and internal network endpoints without moving those assets into Cursor-managed compute.++The important development is not simply "self-hosted agents." It is the explicit separation of the agent control plane from the execution plane:++```text+Cursor control plane Customer execution plane++task intake and UX repositories and worktrees+agent loop and orchestration <---------- outbound worker connection+model access tools, builds, and test suites+run status and coordination caches and internal services+ specialized CPU/GPU hardware+ worker pools and autoscaling+```++This validates a deployment model directly adjacent to Cua's strengths. Cua already supplies portable computer-use runtimes, full desktop sandboxes, reusable pools, and cross-platform control. The opportunity is to make Cua the execution substrate that any agent control plane can target, including coding agents that need GUI applications, non-Linux operating systems, specialized hardware, or infrastructure inside a customer's trust boundary.++## What Cursor announced++Cursor's launch post makes the following claims:++- Self-hosted cloud agents are generally available.+- The customer's codebase, tool execution, and build artifacts remain in the customer's environment.+- Workers can access existing caches, dependencies, and private network endpoints.+- Cursor continues to provide orchestration, model access, and the user experience.+- A lightweight worker connects outbound to Cursor, receives jobs, creates an isolated development environment, and runs the Cursor agent.+- Customers can run workers on their own machines or through integrations including AWS Lambda, Coder, Cloudflare, Daytona, E2B, Modal, Namespace, and Vercel.+- A fleet-management API exposes utilization information and supports customer-built autoscaling.++The announcement describes customer-controlled execution, not a fully self-hosted Cursor stack. Cursor still owns the agent loop and its control-plane services.++## Why this matters++### Enterprise agent adoption is becoming an infrastructure problem++The initial cloud-agent product assumed that a vendor-provided Linux environment was sufficient. This launch recognizes that serious software work depends on resources that are difficult or undesirable to copy into a vendor sandbox:++- private package registries and internal APIs;+- large build caches and monorepo dependencies;+- licensed tools and company-specific developer images;+- regulated source code, credentials, and build artifacts;+- unusual compute, attached devices, or accelerated hardware; and+- operating systems and desktop applications that cannot run in a generic Linux container.++For these customers, the execution environment is part of the product rather than an interchangeable implementation detail.++### The control-plane/execution-plane boundary is becoming a product surface++Cursor's worker protocol is now a strategic boundary. It must cover worker identity, job assignment, environment creation, secrets, logs, artifacts, cancellation, heartbeats, retries, capacity, and teardown. The fleet API adds scheduling and autoscaling concerns on top.++Once this boundary exists, customers will reasonably ask whether they can:++- use a different sandbox or fleet provider;+- place workers in several clouds, regions, or on-premises clusters;+- select workers by OS, architecture, GPU, network, or compliance attributes;+- retain their own telemetry and policy enforcement;+- bring their own model or agent loop; and+- use the execution plane independently of Cursor.++Cursor's current product answers the first question through a provider ecosystem while keeping the agent loop proprietary. Cua can differentiate by treating both sides of the boundary as composable.++## Relationship to Cua++Cua's existing layers map naturally onto this architecture:++| Need | Relevant Cua capability |+| --- | --- |+| Isolated task environment | Cua Sandbox images and lifecycle |+| Warm, reusable capacity | Sandbox pools and durable claims |+| Linux container execution | Container-backed sandboxes |+| Full OS fidelity | macOS, Windows, Linux, and Android VM backends |+| GUI and desktop application access | Cua Driver screenshots, accessibility, and input |+| Code and GUI in one environment | Shared shell, PTY, filesystem, processes, and desktop state |+| Customer-controlled infrastructure | Local runtimes, self-hostable components, and Fleet deployment primitives |+| Agent portability | SDK, MCP, and runtime-neutral action contracts |++The strongest Cua position is broader than "another place to run Cursor workers." Cua can provide a common execution plane for agents that need computers, with infrastructure and agent-loop choice kept independent.++```text+ Agent control planes+ Cursor Codex Claude custom agents+ \ | | /+ portable execution contract+ |+ Cua Sandbox + Fleet+ |+ Linux containers / macOS / Windows / Android+ cloud / on-premises / developer-owned machines+```++## Product implications++### 1. Define the remote worker contract explicitly++Cua should have a crisp, documented contract for attaching an external agent or scheduler to customer-managed capacity. It should specify:++- worker registration and workload identity;+- capability advertisement such as OS, architecture, GPU, region, and image;+- claim, lease, heartbeat, cancellation, and retry semantics;+- ingress-free or outbound-only connectivity;+- secret delivery and redaction boundaries;+- artifact and trajectory ownership;+- policy enforcement and audit events; and+- cleanup guarantees after success, failure, cancellation, or lost connectivity.++The contract should work without requiring Cua to own the agent loop.++### 2. Present pools as an agent-platform primitive++Warm pools are not only a sandbox optimization. They are the capacity layer behind interactive and asynchronous agents. The product story should show how an agent platform asks for a computer with declared capabilities, receives a claim, reconnects when appropriate, and releases it safely.++### 3. Make heterogeneous scheduling visible++Cursor's announcement invites questions about GPUs and unusual environments. Cua can make this first-class by advertising and selecting capacity by:++- operating system and version;+- CPU architecture;+- GPU model and acceleration API;+- memory, storage, and attached devices;+- network placement and allowed destinations;+- image or snapshot lineage; and+- interactive desktop availability.++### 4. Emphasize full-computer workloads++Most named providers in Cursor's announcement are associated with Linux code sandboxes. Cua should clearly demonstrate the workloads that require more than a shell: native desktop builds, browser-plus-terminal workflows, Windows applications, macOS/Xcode automation, Android, GPU-backed graphical applications, and end-to-end tests across real OS interfaces.++### 5. Keep deployment ownership unambiguous++"Self-hosted" can hide several different ownership models. Cua documentation and APIs should name them precisely:++| Layer | Possible owner |+| --- | --- |+| Agent loop and model calls | Cua, another vendor, or the customer |+| Scheduling and control plane | Cua Cloud or customer-operated |+| Worker and sandbox runtime | Cua Cloud, customer cloud, on-premises, or developer machine |+| Source, secrets, tools, and artifacts | Customer-selected boundary |+| Telemetry and trajectories | Customer-selected storage and retention |++A deployment diagram should always show which network receives source code, prompts, screenshots, tool results, artifacts, and model traffic. "Runs in your infrastructure" alone does not answer those questions.++## Proposed follow-up++1. Write a public concept page describing control planes, execution planes, and the ownership options supported by Cua without framing it around a competitor.+2. Publish one reference integration that claims a Cua sandbox or pool from an external agent service through an outbound-only worker.+3. Define a capability schema for OS, architecture, GPU, region, network placement, and desktop availability.+4. Verify and document which Fleet components can be operated in customer infrastructure today, separating current support from intended architecture.+5. Build a representative demonstration in which a remote coding agent runs a task that needs both a terminal and a native desktop application on customer-managed macOS or Windows capacity.++## Confirmed constraints and remaining questions++Cursor's current documentation adds several details beyond the launch announcement:++- Team Pools require an Enterprise plan and authenticate with service-account API keys.+- Workers send Cursor the content needed by the agent, including file contents, terminal output, diffs, screenshots, local MCP results, and routing metadata.+- Cloud Agent artifacts can be uploaded to Cursor-managed storage unless the customer blocks the documented artifact endpoint.+- Team Pools can route work to named pools for GPU machines or Macs, and each pool worker serves one agent at a time.+- Cursor provides a worker controller and pending-request APIs, while the customer remains responsible for infrastructure, worker images, secrets, scaling policy, and production validation.+- Cursor documents private connectivity to GitHub Enterprise Server, GitLab Enterprise, and private source-control APIs.++The following integration questions still require validation for a Cua-backed deployment:++- Can Cursor's worker controller claim and release Cua Fleet capacity without a custom reconciliation layer?+- Which worker and claim identifiers should be shared so both systems recover cleanly after interruption?+- How should Cua capabilities such as OS, architecture, GPU, region, and desktop availability map to Cursor Team Pool selection?+- Does a GitLab CE deployment work through Cursor's documented source-control paths, or is the support limited to GitLab Enterprise?+- Can worker images pin and update the Cursor CLI through a supported non-interactive release channel?+- Can customers replace Cursor's model access or agent loop while retaining any part of the worker integration?++## Sources++- Cursor, [Run cloud agents in your own infrastructure](https://cursor.com/blog/self-hosted-cloud-agents), published 2026-03-25.+- Cursor, [Self-hosted cloud agents documentation](https://cursor.com/docs/cloud-agent/self-hosted).+- Cursor, [Cloud Agents](https://cursor.com/agents).+- Cursor announcement on [X](https://x.com/cursor_ai), observed 2026-09-02. The supplied transcript did not include the individual post URL.+- Cua, [How sandboxes work](content/docs/concepts/how-sandboxes-work.mdx).+- Cua, [SDK, MCP, and process hosting](content/docs/concepts/sdk-mcp-and-hosting.mdx).+- Cua, [Run sandboxes in parallel](content/docs/how-to-guides/sandbox/scale-out.mdx).