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: 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.json
index 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.mdx
new file mode 100644
index 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.md
new file mode 100644
index 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).