Examples

For one-purpose SDK snippets (screenshot, recording, file transfer, keepalive) see use-computer-sdk/python/examples/.

Use the SDK for one-off prompts. Use josancamon19/use-computer-cookbook and Harbor when you need datasets, repeatable runs, multiple agents, or graders.

Harbor setup

Skip this for the SDK adhoc example. Harbor is for running task directories: benchmarks, repeated trials, multiple agents, and graders.

git clone https://github.com/josancamon19/use-computer-cookbook && cd use-computer-cookbook
uv sync
cp .env.example .env

Fill in .env:

USE_COMPUTER_API_KEY=uc_live_…   # from Settings
ANTHROPIC_API_KEY=sk-ant-…       # required by AnthropicCUAAgent / IOSAgent
OPENAI_API_KEY=                  # optional — only for OpenAICUAAgent / Fireworks

The ready-to-run jobs live under src/runner/configs/:

src/runner/configs/
|-- job-adhoc.yaml       # ungraded smoke/prompt task dirs; use SDK adhoc for one prompt
|-- job-cuagym.yaml      # CUA-Gym on Ubuntu snapshots
|-- job-custom.yaml      # custom long-running tasks
|-- job-macosworld.yaml  # macOSWorld tasks with graders
|-- job-osworld.yaml     # OSWorld on Windows or Ubuntu
`-- job-waa.yaml         # Windows Agent Arena

Run any job the same way:

uv run harbor run \
  -c src/runner/configs/job-macosworld.yaml \
  --env-file .env

Some jobs already include tasks: or datasets:. To point the same config at a different task directory, pass -p:

uv run harbor run \
  -c src/runner/configs/job-macosworld.yaml \
  -p datasets/macosworld_ready \
  --env-file .env

The environment block chooses the sandbox:

environment:
    import_path: use_computer.harbor.environment:UseComputerEnvironment
    kwargs:
        gateway_url: https://api.use.computer
        platform: macos
        # platform: ios
        # platform: windows
        # platform: ubuntu

The agents block chooses who drives it. Desktop jobs use desktop agents; iOS uses IOSAgent. Add multiple entries to compare providers on the same tasks.

agents:
    - import_path: use_computer.harbor.agents:AnthropicCUAAgent
      model_name: anthropic/claude-sonnet-4-6
      kwargs:
          max_steps: 50

Adhoc

For a one-off model run, use Computer.adhoc_run. It creates a sandbox, drives the model, polls until completion by default, and returns a RunStatus. It is useful for watching one instruction execute; it is not a graded eval.

pip install use-computer
export USE_COMPUTER_API_KEY=uc_live_...

from use_computer import Computer

client = Computer()  # reads USE_COMPUTER_API_KEY

run = client.adhoc_run(
    "Open Disk Utility and create a 100MB empty disk image on the Desktop.",
    platform="macos",
    model="claude-sonnet-4-6",
    max_steps=50,
)

print(run.status, run.sandbox_id, run.n_steps, run.error)

Use platform="ios" for iOS. Local ANTHROPIC_API_KEY is only for Harbor/cookbook runs; SDK adhoc runs use the hosted run endpoint.

macOS-only coding tasks

Some coding tasks need a real Mac, not just a macOS-looking desktop. src/runner/configs/job-custom.yaml includes two examples: one hits Apple Metal/MLX, the other hits Xcode/Apple SDK tooling. Run them with Claude Code or Codex through Harbor:

uv run harbor run \
  -c src/runner/configs/job-custom.yaml \
  --env-file .env

MLX / Apple Metal

Task dir: datasets/adhoc/macos/optimize-https-huggingface-co-qwen

Optimize https://huggingface.co/Qwen/Qwen3.5-0.8B to run locally on Metal. Ensure sampling is >=2x TPS when compared to HF transformers library and that degradation doesn't go under 95%.

MLX and Metal use Apple's GPU stack on Apple Silicon.

Xcode / Apple SDK

Task dir: datasets/adhoc/macos/clone-https-github-com-permissionlesstech

Clone https://github.com/permissionlesstech/bitchat and ensure all tests pass

Xcode builds and tests depend on Apple's SDKs, toolchains, signing/build behavior, and native simulator/device-facing assumptions.

macOSWorld

macOSWorld is the macOS benchmark. Use src/runner/configs/job-macosworld.yaml for the ready Harbor job config.

Setting up a task's initial state (pre_command)

Each task ships a tests/setup/pre_command.sh that the runner executes inside the sandbox before the agent starts — used to seed files, set an app state, or open a window so every trial begins from a desired state.

# tests/setup/pre_command.sh — file-management task
rm -rf /Users/lume/Documents/benchmark_files/
cp -r /Users/lume/Benchmark_Backup/benchmark_files /Users/lume/Documents
open /Users/lume/Documents/benchmark_files/Multimedia/Separated_images

Some tasks use it to set up a premade note in the Notes app:

# tests/setup/pre_command.sh — Notes task
osascript -e 'tell application "Notes" to make new note with properties {name:"Lorem Ipsum", body:"Dolor Sit Amet"}'

Verifiers

A tests/test.sh is a plain bash check the runner executes against the live sandbox after the agent stops — anything from checking file properties to reading app state or the accessibility tree.

Filesystem expectations are the simplest case — "sort files; delete everything that isn't an image":

# tests/test.sh
SRC=/Users/lume/Documents/benchmark_files/Multimedia/Sources
[ $(ls $SRC/*.jpg 2>/dev/null | wc -l) -eq 6 ] \
  && [ $(ls $SRC/*.{docx,md,txt} 2>/dev/null | wc -l) -eq 0 ] \
  && echo 1 > "$REWARD" || echo 0 > "$REWARD"

Same pattern works for any app that exposes AppleScript or its accessibility tree (tell application "System Events" to tell process … to get value of attribute "AXValue" of …), which covers most of what an agent will touch. Apple's AppleScript Language Guide is the reference.

iOS graders: JSON checker DSL

iOS sims have no shell, so AppleScript / bash graders don't work. Instead, iOS tasks declare a list of checker specs that the gateway evaluates against the live accessibility tree via POST /v1/sandboxes/{id}/grade. The runner builds the bash for you — your task only needs to write the spec list.

// tasks/ios.json (per-task grader override)
{
    "instruction": "In Maps, search for 1177 Market St and start walking directions to 30 Otis St.",
    "checks": [
        { "kind": "foreground_app", "name": "Maps" },
        { "kind": "label_contains", "text": "Directions" },
        { "kind": "label_contains", "text": "1177 Market" },
        { "kind": "label_contains", "text": "30 Otis" },
        { "kind": "label_regex", "pattern": "\\b\\d+\\s*min\\b" }
    ]
}

Supported kinds (all evaluated against the live AX tree):

The grader passes the trial only when every check passes — the top-level passed flag in the gateway's response is the AND of all individual results[].passed. Per-check results are persisted to verifier/grader_checks.json so the dashboard can show which check failed.

Swapping agents

Every job YAML's agents: block accepts a different import_path. Drop in whichever agent you want and Harbor wires the rest. The reusable agents live in the Python SDK; the cookbook uses these canonical Harbor wrappers:

Stack multiple in the same job to compare them — Harbor runs each agent against every trial and reports per-agent reward.

Full reference: github.com/josancamon19/use-computer-cookbook.