// Use Cua's cloud sandboxes via cua.ai. Requires CUA_API_KEY. Cloud sandboxes are isolated VMs run by trycua with billing per usage. Use when the user wants no local Docker/QEMU, wants Windows/macOS guests without Apple Silicon, or explicitly asks for cloud.
Drive the user's host machine directly through Cua, with no sandbox. Maps to Cua's Localhost API. Higher risk - the agent can click, type, and run shell commands on the real desktop. Use only when the user explicitly opts in and read the safety section first. Triggers - "control my computer", "click here", "use my real Chrome", "no sandbox", "내 컴퓨터 자동화".
Mouse, keyboard, and scroll primitives for cua_click / cua_type / cua_key / cua_scroll. Reference for action shapes, modifier keys, key chord syntax, and screenshot-driven targeting workflows.
pi-cua-integration is a Pi/Senpi extension that bridges Cua (trycua/cua) for computer-use sandboxes and host control. MUST USE when the user asks to drive a desktop UI, take screenshots, run a "computer use" task, control a sandbox, or invoke any cua_* tool. Triggers - "cua", "computer use", "sandbox", "screenshot the desktop", "click the screen", "take over the browser", "샌드박스 켜줘", "스크린샷 찍어", "내 컴퓨터에서 자동화".
Run Cua sandboxes locally - no API key required. Covers Docker (XFCE/Kasm) for Linux containers, QEMU for full VMs, Lume for macOS guests on Apple Silicon, and Tart for Apple VZ VMs. Use when the user wants a local sandbox, wants to keep things off the cloud, or asks "spin up an Ubuntu desktop", "open a sandbox VM", "let me try this safely first".
| name | cua-cloud-sandbox |
| description | Use Cua's cloud sandboxes via cua.ai. Requires CUA_API_KEY. Cloud sandboxes are isolated VMs run by trycua with billing per usage. Use when the user wants no local Docker/QEMU, wants Windows/macOS guests without Apple Silicon, or explicitly asks for cloud. |
In mode: "cloud", cua_sandbox_start provisions a sandbox in cua.ai.
Requires a Cua API key (sign up at https://cua.ai/signin).
// .pi/cua.jsonc
{
"mode": "cloud",
"cloud": {
"apiKeyEnv": "CUA_API_KEY",
"region": "north-america"
}
}
Then export the key before launching Pi:
export CUA_API_KEY=sk_cua-...
If the API key env var is empty when the session starts, the extension
prints a warning and falls back to mode: "local" for that session.
cua_sandbox_start({ os: "windows" }) // Windows 11
cua_sandbox_start({ os: "macos" }) // macOS (cloud Lume)
cua_sandbox_start({ os: "linux" }) // Ubuntu container
cua_sandbox_start({ os: "android" }) // Android emulator
Cloud mode is the only way to get macOS/Windows VMs from non-macOS hosts or hosts without Apple Silicon.
Cua bills per sandbox-second. Stop sandboxes promptly with
cua_sandbox_stop. The extension also auto-stops on session shutdown.
The region config sets the data center. Default omitted lets cua.ai
choose. Available regions are listed in the Cua console.