From zero to a verified task

Choose one path: use a hosted/local vision model for your own work, or use the credential-free tutorial to verify installation first. The tutorial runs real NexAU and real GUI/browser tools against a scripted model endpoint; it does not measure autonomous model quality. No E2B, NorthJetty, private dataset or remote filesystem is needed.

1. Install once

Use Python 3.12 (the tested baseline), Git and uv. From a source checkout or extracted release archive:

uv sync --locked --extra local --extra device
uv run --no-sync playwright install chromium
source .venv/bin/activate
northcua --help

On Linux install browser system libraries with uv run --no-sync playwright install --with-deps chromium. Windows PowerShell activation is .venv\Scripts\Activate.ps1; local browser tasks are separate from the macOS/Linux-only local batch tutorial. See installation for wheel installation and troubleshooting for diagnostics.

All following terminals use the same checkout and activated environment. Commands are also available as python -m northcua .... Installation requires downloading public packages and a browser; tutorial execution subsequently needs only loopback.

2A. Use your model: edit only model connection settings

Copy .env.example to .env, fill in the model and API key, and set the API base URL if using another OpenAI-compatible endpoint. Load it explicitly; NorthCUA does not automatically source .env:

cp .env.example .env
# Edit .env before the next command. Keep it private.
set -a
. ./.env
set +a
northcua config init --directory logs/my-config \
  --model "$NORTHCUA_MODEL" --base-url "$NORTHCUA_BASE_URL"
northcua config validate --app-config logs/my-config/app.example.yaml
northcua local web run --app-config logs/my-config/app.example.yaml \
  --url https://example.com --query 'Report the main heading.' \
  --max-steps 8 --session-id first-web

config init creates both agents with the same connection settings and keeps the key as an environment reference. It refuses existing files unless --force is explicitly supplied. The selected model must accept images and structured tool calls. Do not put an API key in --api-key-env: that option takes a variable name. Configuration recipes cover Responses, Anthropic and Gemini.

For Desktop, grant the launching terminal Screen Recording and Accessibility on macOS; Linux needs X11 and DISPLAY; Windows needs an unlocked interactive desktop. Run only one Desktop task on a physical display:

northcua local desktop run --app-config logs/my-config/app.example.yaml \
  --query 'Open a calculator and compute 12 * 7.' --max-steps 15 --session-id first-desktop

Desktop has one observation path: GUI tools return screenshots. No observation mode, driver or private service needs configuring. Read the terminal result and inspect its artifact path; a model claiming completion is not by itself proof that the requested outcome happened.

2B. Verify locally without a model key

In terminal A, keep this service running:

northcua demo serve --directory logs/tutorial

Wait for a JSON line with "ready": true. This creates app/agent configuration, batch.yaml, demo.json and a loopback-only service at http://127.0.0.1:8787. It refuses a nonempty directory so it cannot overwrite earlier evidence. Choose another directory for a new tutorial run. No API environment variables are needed.

In terminal B:

northcua config validate --app-config logs/tutorial/app.example.yaml
northcua local web run --app-config logs/tutorial/app.example.yaml \
  --url http://127.0.0.1:8787/task/first-web \
  --query 'Task ID: first-web. Activate the button and verify the receipt.' \
  --session-id first-web --max-steps 6 --evaluate

Success means all of the following: the command exits 0; the actor finishes; the evaluation report says success; logs/tutorial/events.jsonl contains a web_action for first-web and an evaluation with verified: true. The check matches the task ID in the query against that page's task-specific receipt. Keep Task ID: first-web aligned with /task/first-web when using the scripted endpoint. The evaluator reads the changed page in the same live browser session. Reopening the page does not retain the receipt.

3. Verify native Desktop input

Stop terminal A with Ctrl-C, then start a fresh fixture directory with a native form:

northcua demo serve --directory logs/tutorial-desktop --desktop

This needs Tk (python -c 'import tkinter') and the desktop permissions above. A small NorthCUA tutorial — disposable form window must be visible. Leave that window available and avoid other mouse/keyboard work during this task. The demo focuses only its own form before the actor types.

In terminal B:

northcua local desktop run --app-config logs/tutorial-desktop/app.example.yaml \
  --query 'Fill the disposable tutorial form and press Enter.' \
  --session-id first-desktop --max-steps 6
python - <<'PY'
import json
from pathlib import Path
p = Path('logs/tutorial-desktop')
expected = json.loads((p / 'demo.json').read_text())['desktop_text']
assert (p / 'desktop-result.txt').read_text() == expected
print('PASS: native form contains this run’s expected text')
PY

The actor goes through NexAU → note/type/keypress → native tools. Check the saved screenshots and terminal status too. Desktop evaluation is off in this smoke configuration; the native form receipt is the task-specific outcome check.

4. Find evidence and stop

The CLI prints the artifact directory. Demo agent artifacts live under the generated directory's artifacts/; events.jsonl records only fixture activity, not a replacement for the full trace. Results and evaluation explain actor status, evaluation verdict and the optional viewer.

Ctrl-C the demo terminal to close the fixture server and its disposable window. Keep output directories for inspection. Continue with local batch and recovery, service deployment, or Agent skills.