Provision an amd64 Omarchy desktop on Cua Fleet and control it with the Cua Sandbox SDK.
Use the Cua Sandbox SDK to provision an amd64 Omarchy desktop on
[Cua Fleet](/docs/tutorials/your-first-cloud-fleet). Fleet runs the Omarchy system
as a KubeVirt containerDisk
; the guest starts Hyprland and exposes both the
cua-computer-server
API and the Cua Driver MCP service.
This guide is for the amd64 Fleet image. The Omarchy on Apple Silicon guide builds a separate ARM64 VM for local Lume use and does not run on Fleet.
Use an immutable image digest. The example digest below passed two fresh Fleet claims with
screenshot, shell, mouse, keyboard, clipboard, window discovery, and workspace hotkey checks.
Fleet admission and image availability must be enabled for your account before a claim can start.
Do not replace the digest with latest
in production automation.
Before you start# #
You need:
- Python
`>=3.11,<3.14`
; ;`uv`
`cua-sandbox==0.4.3`
; and- a Fleet access token or OAuth client credentials that can manage pools.
The Fleet-verified image reference is:
The image is an amd64 KubeVirt containerDisk. It is not an ordinary OCI
application image: the image contains a bootable disk at /disk/disk.img
. Fleet pulls the approved image with its registry credentials, so you do not need AWS credentials on the machine that runs this script.
Authenticate with Fleet# #
The SDK connects to https://run.cua.ai
by default. Export one supported credential set before running the example:
Or use OAuth client credentials:
Keep credentials in your shell environment or a secret manager. Do not put them in the image definition or commit them to source control.
Choose a globally unique, lowercase DNS-label pool name:
Provision and claim an Omarchy desktop# #
Save this script as run_omarchy_fleet.py
:
Run the script:
Pool.apply()
creates or reconciles the named pool and its template. The
server
service on port 8000
carries screenshot, shell, keyboard, mouse, and
clipboard operations. The mcp
service on port 3000
carries the Cua Driver
MCP endpoint at /mcp
for an MCP client. The pool name is globally unique across Cua accounts. If the name is already in use, choose another name and run the script again:
## View the desktop[#](#view-the-desktop)
The Fleet transport in `cua-sandbox==0.4.3`
does not expose a browser or VNC
display URL. Use sandbox.screenshot()
to inspect the desktop and the mouse,
keyboard, shell, clipboard, and window interfaces to control it. The image's
WayVNC process is for image diagnostics and is not part of the public Fleet
service contract.
Connect an MCP client# #
The claim exposes the Cua Driver MCP service as the named Fleet service
mcp
. Use the SDK service interface while the claim is active:
For a complete MCP client, use the Cua Driver MCP tool reference and keep the authenticated Fleet claim alive for the duration of the client session.
Keep or delete the pool# #
The example sets a six-hour creation-age TTL and deletes the pool in finally
.
That is a good default for jobs and CI. If you want a reusable warm pool, omit
the finally
deletion and release only the claim; delete the pool explicitly when you are finished:
Deleting the pool removes its template and sandboxes. Save screenshots or files that you need before the claim and pool are deleted.
Troubleshoot startup# #
HTTP 403 during confirm the image repository is included in Fleet admission policy and that your credentials can create a pool in the selected namespace.Pool.apply()
:Claim timeout: verify that the image is an amd64 KubeVirt containerDisk, the image reference includes the exact digest, and theserver
service is configured on port8000
.Black or empty screenshot: check the image's unattended Hyprland boot and thecua-computer-server
service before debugging the Fleet transport.MCP connection failure: claim the sandbox with themcp
service exposed on port3000
and send requests to/mcp
throughsandbox.services
.
For local Omarchy development and ARM64 compatibility notes, see [Run Omarchy on
Apple Silicon](/docs/how-to-guides/lume/run-omarchy-arm64).