Quickstart

This guide gets you from zero to a working computer-use agent.

No account? No problem. The hello-world example below runs entirely with local Docker — no API key required. You only need a Cua account when you want cloud sandboxes or to run the AI agent against a hosted model.

Prerequisites: Python 3.12 or 3.13 and Docker (for local sandboxes).

1. Install

pip install cua

2. Hello World

Create hello.py:

import asyncio
from cua import Sandbox, Image

async def main():
    # local=True uses Docker — no API key needed
    # remove local=True to run on Cua Cloud (requires CUA_API_KEY)
    async with Sandbox.ephemeral(Image.linux(), local=True) as sb:
        result = await sb.shell.run("uname -a")
        print(result.stdout)

        screenshot = await sb.screenshot()
        with open("screenshot.png", "wb") as f:
            f.write(screenshot)
        print("Screenshot saved to screenshot.png")

asyncio.run(main())

python hello.py

The sandbox is created, used, and destroyed automatically. No pre-provisioning needed.

3. Run an Agent

To add AI, you need a Cua account and an API key:

pip install cua-cli
cua auth login   # opens browser, saves key locally

Then create agent.py:

import asyncio
from cua import Sandbox, Image, ComputerAgent

async def main():
    async with Sandbox.ephemeral(Image.linux()) as sb:
        agent = ComputerAgent(
            model="cua/anthropic/claude-sonnet-4-5",
            tools=[sb],
        )
        messages = [{"role": "user", "content": "Open Firefox and go to google.com"}]
        async for result in agent.run(messages):
            for item in result["output"]:
                if item["type"] == "message":
                    print(item["content"][0]["text"])

asyncio.run(main())

python agent.py

4. Watch the Agent Live (Optional)

Call get_display_url(share=True) to get a shareable browser link to the live desktop — no CLI needed:

import asyncio
from cua import Sandbox, Image, ComputerAgent

async def main():
    async with Sandbox.ephemeral(Image.linux()) as sb:
        url = await sb.get_display_url(share=True)
        print(f"Watch live: {url}")  # open this in your browser

        agent = ComputerAgent(
            model="cua/anthropic/claude-sonnet-4-5",
            tools=[sb],
        )
        messages = [{"role": "user", "content": "Open Firefox and go to google.com"}]
        async for result in agent.run(messages):
            for item in result["output"]:
                if item["type"] == "message":
                    print(item["content"][0]["text"])

asyncio.run(main())

5. Clean Up

Ephemeral sandboxes delete themselves. For persistent sandboxes:

cua sb ls                           # show all running sandboxes
cua sb delete my-agent-sandbox      # delete when done

Next Steps

Sandbox Lifecycle — ephemeral, persistent, and connect patterns
Images — install packages and configure the environment
Parallel Sandboxes — run multiple agents concurrently
Using the Agent SDK — advanced agent configuration

Was this page helpful?