From zero to your first task.

First, make the environment ready.

Use the project checkout, Python and uv. The first-run guide covers operating-system permissions, Chromium, the model configuration and the difference between a scripted installation check and a real model task.

Set up your model once

From an installed checkout with its environment activated. Copy .env.example, edit the model, API key and endpoint, then load it explicitly.

cp .env.example .env
# Edit .env before continuing. 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

DESKTOP

Desktop

After model setup. Use an interactive desktop and grant the required OS permissions; one task per 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

WEB

Web

After model setup and Chromium installation. Inspect the saved output rather than relying only on the model’s completion message.

northcua local web run \
  --app-config logs/my-config/app.example.yaml --url https://example.com \
  --query "Report the main heading." --max-steps 8

BATCH

Local batch

First start the tutorial fixture and controller in separate terminals using the local-batch guide. They create the three-task manifest below. This no-key tutorial uses a scripted model.

northcua batch validate --manifest logs/batch-tutorial/batch.yaml
northcua batch run --manifest logs/batch-tutorial/batch.yaml \
  --output-dir logs/batch-tutorial/batches
northcua batch status --batch-id local-web --output-dir logs/batch-tutorial/batches

Local batches use fresh Web workers on macOS/Linux and share the host filesystem, user and network. They are not OS sandboxes. Run one Desktop task per physical display.

Let your agent learn the workflow.

The repository skill covers prerequisites, configuration, desktop, web, batches, inspection and cleanup. Give the skill to your coding agent together with its linked references.

Download SKILL.md ↓

Keep the references close.

Your first task — Install, configure your model, run a task and inspect a concrete outcome.

Your model, your endpoint — Copy the template. Set model, key and endpoint; keep credentials on your computer.

A small local batch — Three Web tasks, bounded concurrency, outcome receipts, drain and resume.

For your coding agent — Load the operator skill together with its linked from-zero guides.

Reference documents retain their source language. The complete setup remains available without a public GitHub URL.