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: document OpenClaw on Cloud Fleet
Francesco Bonacci70ae3b43c0f9
diff --git a/docs/content/docs/how-to-guides/sandbox/meta.json b/docs/content/docs/how-to-guides/sandbox/meta.jsonindex a2e0489035..2beefcacb0 100644--- a/docs/content/docs/how-to-guides/sandbox/meta.json+++ b/docs/content/docs/how-to-guides/sandbox/meta.json@@ -5,6 +5,7 @@"create-pool-with-python","create-pool-with-typescript","expire-pools-and-claims",+ "run-openclaw-on-cloud-fleet","run-omarchy-on-cloud-fleet","connect-to-omarchy-with-novnc","secrets",diff --git a/docs/content/docs/how-to-guides/sandbox/run-openclaw-on-cloud-fleet.mdx b/docs/content/docs/how-to-guides/sandbox/run-openclaw-on-cloud-fleet.mdxnew file mode 100644index 0000000000..10b0689d2e--- /dev/null+++ b/docs/content/docs/how-to-guides/sandbox/run-openclaw-on-cloud-fleet.mdx@@ -0,0 +1,271 @@+---+title: Run OpenClaw on Cloud Fleet+description: Run OpenClaw's bundled CUA computer-use provider in an isolated Linux desktop on Cua Cloud Fleet.+---++import { Callout } from 'fumadocs-ui/components/callout';++This guide provisions one Linux desktop on [Cua Cloud Fleet](/tutorials/your-first-cloud-fleet), installs OpenClaw, and connects a local Gateway and node runtime in the same VM. The node's bundled `cua-computer` plugin calls the pinned `@trycua/cua-driver` SDK directly, so the normal OpenClaw `computer` tool can control the VM's graphical desktop.++```text+OpenClaw agent+ -> Gateway+ -> paired local node+ -> computer.act / screen.snapshot+ -> bundled cua-computer provider+ -> @trycua/cua-driver SDK+ -> X11 desktop in the same Fleet VM+```++<Callout type="warn">+ The supported Linux proof path is a glibc-based Linux x64 or ARM64 guest with an X11 desktop. Do+ not use native Wayland as evidence for this integration: OpenClaw documents it as unsupported for+ the bundled Linux provider.+</Callout>++## Before you start++You need:++- Python `>=3.11,<3.14` and [`uv`](https://docs.astral.sh/uv/);+- Node.js and npm in the guest image (the public image used below includes both);+- Fleet credentials that can create pools and claims; and+- a vision-capable model credential for the OpenClaw agent.++The example uses this immutable, public KubeVirt containerDisk:++```text+public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04@sha256:82702ebdd32d1f8fc05f2ea409a7c67d0ba9f8f8e4e4f1a89ce40989d5f4475d+```++It boots Ubuntu 24.04 with XFCE on X11 and exposes the Cua computer server as+the Fleet `server` service on port `8000`. Use an image with the same properties+if you substitute your own image.++## Authenticate with Fleet++The SDK connects to `https://run.cua.ai` by default. Export either a Fleet+access token or OAuth client credentials:++```bash+export FLEETS_TOKEN="<your-access-token>"+# Or:+export CUA_CLIENT_ID="<your-client-id>"+export CUA_CLIENT_SECRET="<your-client-secret>"+```++Keep credentials in the environment or a secret manager. Never put them in an+image definition or commit them to source control. Choose a globally unique,+lowercase pool name:++```bash+export CUA_POOL_NAME="<unique-lowercase-name>"+```++## Provision and claim a desktop++Save this script as `run_openclaw_fleet.py`:++```python title="run_openclaw_fleet.py"+# /// script+# requires-python = ">=3.11,<3.14"+# dependencies = [+# "cua-sandbox",+# ]+# ///++import asyncio+import os+from pathlib import Path++from cua_sandbox import Image, Pool+++IMAGE = (+ "public.ecr.aws/k5j5w0x5/cua-ubuntu-24.04"+ "@sha256:82702ebdd32d1f8fc05f2ea409a7c67d0ba9f8f8e4e9f1a89ce40989d5f4475d"+)+POOL_NAME = os.environ["CUA_POOL_NAME"]+++async def run(sandbox, command: str) -> None:+ result = await sandbox.shell.run(command)+ if not result.success:+ raise RuntimeError(f"{command}\n{result.stderr}")+ if result.stdout.strip():+ print(result.stdout.strip())+++async def main() -> None:+ pool = await Pool.apply(+ Image.from_registry(IMAGE, os_type="linux", kind="vm"),+ name=POOL_NAME,+ replicas=1,+ cpu=4,+ memory_mb=8192,+ services={"server": 8000},+ ttl_seconds_after_created=21600,+ )++ try:+ async with pool.claim(service="server", time_to_start=1800) as sandbox:+ print(f"Sandbox: {sandbox.name}")+ await run(sandbox, "uname -a")+ await run(sandbox, "printf 'DISPLAY=%s\\n' \"$DISPLAY\"")+ await run(sandbox, "test -S /tmp/.X11-unix/X1")++ # Install OpenClaw in the disposable VM. Pin the version you tested.+ await run(sandbox, "npm install --global [email protected]")+ await run(sandbox, "openclaw plugins enable cua-computer")+ await run(+ sandbox,+ "openclaw doctor --lint --only cua-computer/driver-artifacts",+ )++ print("Desktop preflight and bundled CUA artifact check passed")+ screenshot = Path("openclaw-fleet-preflight.png")+ screenshot.write_bytes(await sandbox.screenshot())+ print(f"Screenshot: {screenshot.resolve()}")+ finally:+ await pool.delete()+++asyncio.run(main())+```++Run it with `uv`:++```bash+uv run run_openclaw_fleet.py+```++`Pool.apply()` reconciles the named pool and its VM template. `pool.claim()`+waits for the `server` service and releases the VM when its context exits. The+`finally` block deletes the pool, including warm replicas, even when setup+fails. Save any screenshots or files you need before cleanup.++The script is a disposable preflight. To continue into an agent session, keep+the claim open and run the Gateway, node, pairing, and agent commands in the+same `async with pool.claim(...)` block (or remove the `finally` deletion and+use a second controller that holds the claim). Do not let the claim exit before+the Gateway and node have finished their work.++## Configure the Gateway and node++For a disposable single-VM setup, keep the Gateway on loopback and run the+node in the same user session. Set a temporary Gateway token and configure the+tool policy:++```bash+export OPENCLAW_GATEWAY_TOKEN="<random-long-token>"++openclaw config set gateway.mode local+openclaw config set gateway.bind loopback+openclaw config set gateway.auth.mode token+openclaw config set gateway.auth.token "$OPENCLAW_GATEWAY_TOKEN"+openclaw config set tools.alsoAllow '["computer"]'+```++Start both processes from the X11 session. Keep the logs so you can inspect+pairing and provider advertisements:++```bash+nohup openclaw gateway run --token "$OPENCLAW_GATEWAY_TOKEN" \+ > ~/openclaw-gateway.log 2>&1 &++DISPLAY="$DISPLAY" nohup openclaw node run \+ --host 127.0.0.1 --port 18789 \+ --token "$OPENCLAW_GATEWAY_TOKEN" \+ --display-name "Fleet Linux node" \+ > ~/openclaw-node.log 2>&1 &+```++The node must advertise both `computer.act` and `screen.snapshot`. Approve the+new command surface on the Gateway:++```bash+openclaw nodes pending+openclaw nodes approve <requestId>+openclaw nodes status+```++Repeat `openclaw nodes status` after approval and confirm that the connected+node reports provider id `cua-computer`. If you change the node's advertised+capabilities, approve the new pending request again.++## Run an agent turn++Configure a model using the normal OpenClaw onboarding or provider setup, then+run a Gateway-backed agent turn:++```bash+openclaw agent --message \+ "Use the computer tool to open a visible desktop message that says OPENCLAW CUA FLEET PASSED." \+ --json+```++The agent should make a fresh `computer` screenshot, perform input through+`computer.act`, and observe the resulting screen. Verify the effect in the VM+with the Cua Sandbox screenshot API or your image's desktop viewer. A passing+run has all of these properties:++- the model request includes the normal `computer` tool;+- the node is paired and connected with `computer.act` and `screen.snapshot`;+- the node provider is `cua-computer`;+- the OpenClaw agent completes the turn without a `COMPUTER_*` error; and+- the requested text is visible in an X11 window in the Fleet VM.++The external `cua-driver mcp` server is not part of this path. The bundled+provider uses the npm SDK in-process on Linux; do not install a standalone+driver executable or configure an MCP server for this proof.++## Troubleshoot++- **No `DISPLAY` or an empty screenshot:** run the node from the interactive+ X11 session and confirm `/tmp/.X11-unix/X1` exists. A headless shell without+ the desktop session cannot provide computer use.+- **Wayland session:** switch the image to X11. Native Wayland is not a+ supported proof path for the bundled Linux provider.+- **`computer` is missing:** add `computer` to `tools.alsoAllow`. Sandboxed+ agents also need `tools.sandbox.tools.alsoAllow: ["computer"]`.+- **Node is connected but has no computer commands:** run+ `openclaw plugins enable cua-computer`, rerun the focused doctor check, and+ restart `openclaw node run`. Approve the resulting request with+ `openclaw nodes approve`.+- **Driver artifact errors:** run+ `openclaw doctor --lint --only cua-computer/driver-artifacts`. Reinstall the+ same OpenClaw version; do not replace native package files manually.+- **Fleet claim timeout or HTTP 403:** verify that the image is an admitted,+ immutable KubeVirt containerDisk and that your credentials can create pools.+ Pool names are globally unique, so choose another name if the name is taken.++## Validated configuration++This procedure was exercised end to end with:++| Component | Tested value |+| -------------- | ------------------------------------------------------------- |+| OpenClaw | `2026.8.1`, commit `6dc72d7ee21947f8bec897f76de5214e3830ffd4` |+| Cua | commit `e7295472e196b22e1d02a69441b315a3776d50fb` |+| Cua Driver SDK | `@trycua/cua-driver` `0.21.0` |+| Guest | Ubuntu `24.04.4`, Linux x86_64 |+| Desktop | XFCE on X11, `DISPLAY=:1` |+| Fleet | KubeVirt, BIOS, 4 vCPU, 8192 MB, one replica, `server:8000` |+| Image | Ubuntu 24.04 containerDisk pinned by the digest above |++The exercised agent session completed five `computer` calls with zero failures+and produced a visible desktop result. The pool was deleted after the run.++## Clean up an interrupted run++If the process is interrupted after `Pool.apply()`, rerun it with the same+`CUA_POOL_NAME`. `Pool.apply()` reconciles the existing pool, and the `finally`+block reaches the deletion path when connectivity returns. You can also delete+the pool explicitly after reconnecting:++```python+await pool.delete()+```++For reusable warm capacity, omit the deletion and set a suitable pool and claim+TTL. See [Create a reusable sandbox pool with Python](/how-to-guides/sandbox/create-pool-with-python).diff --git a/docs/content/docs/use-cua-with/openclaw.mdx b/docs/content/docs/use-cua-with/openclaw.mdxindex 1d6a39b588..d5b7bccd06 100644--- a/docs/content/docs/use-cua-with/openclaw.mdx+++ b/docs/content/docs/use-cua-with/openclaw.mdx@@ -24,6 +24,6 @@ openclaw mcp set cua-driver '{"command":"/absolute/path/to/cua-driver","args":["documented embedding path.</Callout>-Continue with [Connect your agent to Cua Driver](/how-to-guides/driver/connect-your-agent#other-supported-clients). To run OpenClaw inside a Cua-managed Linux VM, use [Run OpenClaw in a Lume VM](/how-to-guides/lume/run-openclaw).+Continue with [Connect your agent to Cua Driver](/how-to-guides/driver/connect-your-agent#other-supported-clients) for the separate MCP architecture. To run the bundled provider inside an isolated Linux Fleet VM, use [Run OpenClaw on Cloud Fleet](/how-to-guides/sandbox/run-openclaw-on-cloud-fleet). For a local macOS VM, use [Run OpenClaw in a Lume VM](/how-to-guides/lume/run-openclaw).Upstream: [OpenClaw MCP CLI documentation](https://docs.openclaw.ai/cli/mcp).