NorthCUA documentation

This repository provides the NorthCUA Harness for Desktop and Web agents. It connects a request to actions, observations, outcome checks and a durable execution record. Start with one local task, then choose the deployment and evaluation path your workload needs. Commands, Python imports and package names use northcua.

Start here

Your goal	Guide
Start from zero, with model templates or no-key local checks	First run
Let an external Agent operate the project	Operator skill and skill guide
Run three real local browser tasks and resume	Local batch tutorial
Understand what the harness provides	System tour
Install and run a first Desktop/Web task	Getting started
Choose a provider, tool surface and budgets	Configuration
Inspect what happened and judge the result	Evaluation and artifacts
Find and fix a failure	Troubleshooting

Run and scale

Execution modes covers Python, CLI, local WebSocket serving and controller/device deployment. Batch execution adds attempt isolation, preparation, persistent recovery and reporting. Environments covers public E2B templates and upstream OSWorld integration.

Understand and extend

Context and memory explains visual windows, compaction and notes. Architecture connects those mechanisms to the code and package boundaries. The paper map links the research design to concrete implementations and regression coverage. Contributing describes the development workflow.

Check the evidence

Testing gives reproducible commands. Verification records what actually ran and the scope of independent reviewer signoffs. Clean scope explains removals, retained compatibility and open decisions. Security describes operational boundaries and reporting.

Use northcua config schema --kind app or --kind batch for complete generated JSON schemas and --help for optional CLI flags. Tutorials use supported public examples. Deterministic tests and research illustrations are labeled so they can be distinguished from real-model evaluations.