Cua Docs

Control the desktop with Cua Driver

Connect the typed Cua Driver SDK to a claimed Cloud Fleet computer.

Cua Driver provides typed desktop inspection and control. Use the Sandbox interfaces backed by computer-server for shell commands, files, and interactive terminals; the Driver connection does not replace those APIs.

Python uses the Sandbox SDK, while TypeScript uses the Fleet SDK for hosted lifecycle and routing. The TypeScript Fleet SDK is not a TypeScript Sandbox SDK. Both examples below connect Driver to the same advertised guest service.

Prerequisites#

  • An authenticated Cloud Fleet client and a live claim. The Python example starts with the Pool object for that capacity; the TypeScript example starts with its Fleet client and claim.
  • A guest service named mcp that advertises the typed Driver envelope extension, capabilities.experimental["ai.cua.driver.envelopes"].version == 1. An ordinary MCP tools endpoint is not enough.
  • Guest permissions for the desktop operation you call. Connecting Driver does not elevate permissions or make every operation available on every desktop.

No Fleet image is implied to provide this capability. Qualify the exact guest artifact and matching Driver bindings before relying on it.

Connect and inspect the desktop#

Install the Sandbox SDK with its optional Driver dependency:

python -m pip install --extra-index-url https://wheels.cua.ai/simple 'cua-sandbox[driver]'

Claim from the existing pool, then connect the typed Driver through its advertised mcp service:

from cua_driver import GetScreenSizeInput
 
 
async def inspect_desktop(pool):
    async with pool.claim(service="server") as sb:
        # sb.shell, sb.files, and sb.terminal continue to use computer-server.
        async with sb.driver.connect(service="mcp", transport="mcp") as driver:
            result = await driver.get_screen_size(
                GetScreenSizeInput(session=None)
            )
            if result.is_error:
                raise RuntimeError(result.text)
            print(result.text)

Exiting the inner context closes Driver before the outer claim context releases the claim.

The returned object is the typed Cua Driver interface, not a wrapper around MCP tools. Keep the claim and authenticated client alive for the whole Driver connection. Copy any results you need out of the guest, close Driver, and only then release the claim. Releasing a claim first can interrupt cleanup and leave the outcome of an in-flight desktop action uncertain.