Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/trycua/cua/llms.txt

Use this file to discover all available pages before exploring further.

Cua Bench lets you evaluate computer-use agents against verifiable tasks on real or simulated desktops. This guide walks you from a fresh machine to a completed benchmark run, including inspecting scores and trajectories.

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Python 3.12 or 3.13 — Cua Bench requires Python 3.12 or 3.13.
  • uv — the recommended package manager for installing Cua Bench and its extras.
  • Docker — required for native-provider tasks that run inside containers.

​
Install Cua Bench

1

Clone the Cua repository

git clone https://github.com/trycua/cua.git
cd cua
2

Install the CLI and its dependencies

Navigate to the cua-bench library directory and install it as an editable tool:
cd libs/cua-bench
uv tool install -e .
For simulated-provider tasks that run in a browser, add the browser extra and install the Chromium engine:
uv tool install -e '.[browser]'
uv tool run --from 'cua-bench[browser]' playwright install chromium
3

Confirm the CLI is available

cb --help
You should see command groups: run, interact, task, trace, dataset, image, agent, platform, and status.

​
Create a base environment image

Native-provider tasks need a container image that matches their operating-system type. Build the default base image before running any native task: 
cb image create linux-docker
This command pulls the base OS layer, applies Cua Bench’s desktop configuration, and tags the result so the runner can find it. The first build takes a few minutes; subsequent runs reuse the cached layers.
You can list available images at any time with cb image list and inspect a specific image with cb image info <name>.

​
Run a built-in dataset

The cua-bench-basic dataset contains browser-based UI interaction tasks that exercise clicking, typing, drag-and-drop, form filling, and more. Run it with four parallel workers: 
cb run dataset datasets/cua-bench-basic \
  --agent cua-agent \
  --max-parallel 4
The runner assigns tasks to workers, streams live status to the terminal, and writes results to the current directory when finished.
The cua-agent value selects the built-in Cua computer-use agent. You can substitute a custom agent by passing a path to your agent module. See Run Benchmark for details.

​
Understanding the output

When the run completes, the terminal prints a summary table: 
Run ID: run-a1b2c3
─────────────────────────────────────────────────
 Task                  Variant  Reward  Steps
─────────────────────────────────────────────────
 click-button          0        1.0     3
 fill-form             0        1.0     8
 drag-drop             0        0.0     12
 select-dropdown       0        1.0     4
 toggle-switch         0        1.0     2
─────────────────────────────────────────────────
 Total tasks: 14   Successes: 11   Avg reward: 0.79
 Duration: 94.3 s
Each row shows the task name, the variant index that was run, the reward returned by the evaluator (between 0.0 and 1.0), and the number of agent steps taken. The footer reports the aggregate success count, average reward, and total wall-clock time. Trajectory files are written alongside the summary. Each trajectory captures the full sequence of observations and actions, which you can inspect with: 
cb trace view <run-id>

​
Next steps

Tasks

Understand the task lifecycle and write a custom task in Python.

Run Benchmark

Explore all cb run flags including output directories, model overrides, and RL export.

Task registry

Browse community-published tasks and datasets.

CLI reference

Full reference for every cb command group and flag.

Build docs developers (and LLMs) love

Get started for freeTalk to us