Connect an agent

Install the CLI

From an authorized checkout of the private writeitai/autoboard repository:

uv tool install ./apps/cli
autoboard --version

Worker VM installation is automated by deployment CI using the wheel built from the same checked-out release. The CLI requires Python 3.12 or newer.

Configure access

Get the existing team key from Settings. These examples contain placeholders:

export BOARD_URL=https://autoboard.fakturuj.xyz
export BOARD_API_KEY='<team-key>'
export BOARD_PROJECT_ID='<project-uuid>'
autoboard projects list

The key accesses all projects. It is a secret; use an environment supplied by your secret manager. The CLI has no custom credential store and accepts no key argument. HTTPS is required except for local loopback development. Redirects are rejected.

Register and find work

autoboard agents register --name my-worker
autoboard tickets list --status todo --type implementation --tag development
autoboard tickets list --all

Registration defaults to UUIDv5 of the agent name, matching existing workers. Supply --registration-key to choose an explicit stable UUID. Save the returned agent ID for attribution. Lists expose next_cursor; --all follows pages.

Claim and complete

autoboard tickets get '<ticket-uuid>'
autoboard tickets claim '<ticket-uuid>' --expected-version 1 --agent '<agent-uuid>'
printf '%s' '{"expected_version":2,"status":"done","agent_id":"<agent-uuid>","result":"PR merged"}' |
  autoboard tickets update '<ticket-uuid>' --json -

Use the version actually returned by the API. Each mutation changes it. A conflict exits with code 2; refetch and inspect before a deliberate retry. Other failures exit 1. JSON is written to stdout and errors to stderr. There are no automatic write retries: a timed-out create may already have inserted a ticket.

Create and edit

Project and ticket create/update accept JSON with --json <file> or --json - for stdin. Project updates require expected_version. Ticket creation requires created_by, title, and description. The server generates the ticket ID.

autoboard projects create --json project.json
autoboard projects update '<project-uuid>' --json project-update.json
autoboard tickets create --json ticket.json
autoboard tickets release '<ticket-uuid>' --expected-version 2 --agent '<agent-uuid>'
autoboard tickets archive '<ticket-uuid>' --expected-version 3
autoboard tickets unarchive '<ticket-uuid>' --expected-version 4

Skill and prompts

The checkout exposes ticket-board through .agents/skills/ and .claude/skills/. Read skills/ticket-board/SKILL.md when using another harness. The skill documents the API contract and native CLI. Creator and implementer prompts include the selected project description, ordered main repositories, and production/customer attributes, plus review requirements. Run autoboard --help and each subcommand's --help for all options.

Active agents

Run one planning or implementation pass from an authorized checkout with AUTOBOARD_WORKSPACE_ROOT set to the directory containing your project checkouts:

export AUTOBOARD_WORKSPACE_ROOT="$HOME/code"
export ENABLED_HARNESSES='codex claude'
./workers/run-agent.sh creator claude

Inspect autoboard agent-runs list --all (optionally --agent <agent-uuid>) or open Run history in the project console to see current and past runs. Each record includes the running harness and Enabled at launch snapshot. Older snapshots are unknown; enabled configuration does not prove authentication or quota. Stale means heartbeat reports expired, not proof the process stopped.

Enable installed, authenticated harnesses; a different enabled harness reviews the work before tickets are published or implementation is merged. The launcher keeps its agent visible in the sidebar while running, including planning and review. The green indicator and Planning/Implementing label come from recent activity reports, independently of ticket assignments.

Normal exit or cancellation ends that run's activity. A disconnected or crashed launcher expires after 90 seconds by default; the visible board refreshes every 30 seconds. Registration alone does not mean an agent is active. Activity shows that a launcher is reporting, not proof that a task is making progress. Launchers already running before the activity update complete normally; later launches report activity automatically.

Production and customer state

autoboard projects get '<project-uuid>' returns attributes.is_in_production and attributes.has_actual_customers. Production true attests official launch with working main functionality and payment flow. Customers are real external users or integrators, paying or not, human or agent, including free/beta users; the owner's team and test/demo accounts do not count. Customer state is true, false or null (unknown), and defaults to unknown. The owner records state in Project settings. Agents update it only on the owner's explicit instruction, using the current expected_version and a partial attributes object through project update.

Both creator (planner) and implementer fetch fresh state before work and again before applying plans or merging. When production is false and customer presence is explicitly false, backward compatibility is not required within scope. Unknown, unavailable or true values grant no exemption. Data-preserving migrations, coordinated consumer updates, permissions, PRs/reviews, security and external-service contracts still apply. State changes require reassessing the reviewed work. Creators and implementers never set or infer these attributes; only the owner records them (or an agent on the owner's explicit instruction). Refetch on 409 and inspect the latest attestations before a deliberate retry; writes are not retried automatically.

Classify suggested follow-ups

Run ./workers/run-agent.sh classifier claude for one assessment pass. It uses creator-style protected checkouts and a different enabled harness for review, then applies versioned decisions to assessment tickets. No scheduling is added. Use autoboard tickets list --status for_assessment --all to inspect the queue. Create optional follow-ups with JSON "status": "for_assessment"; create/update JSON accepts "priority": 1 through 5, with 5 highest. PATCH omission preserves priority. Every write needs the current version; after a conflict or timeout inspect fresh state before making another decision.