First agent run

This picks up where the quick start ends and goes as far as a task that a machine of yours will take on its own. Eight steps, and three different people can be involved: the instance administrator, the project’s owner, and the person who hands the work over — on a small team these are often the same person.

#	Step	Who	Where
1	Create the project	Instance administrator	Projects → New Project
2	Add the people	Instance administrator, then the project’s owner	Settings → Users, then the project’s Settings → General
3	Name the repository	Project owner	Project Settings → Integrations
4	Switch agent runs on	Project owner	Project Settings → Workers
5	Connect a machine	The person handing work over	The menubar app on their Mac, and a browser
6	Choose an agent	Anyone who can edit the task	The task’s Agent row
7	Assign it to yourself	The person whose machine will run it	The task’s Assignee row
8	Move it to the approved column	Anyone who can edit the task	The board

Nothing runs until all eight are true. Once an agent is chosen, and while the task has not left the approved column, the task itself tells you which of the rest are not: under its Agent row it lists everything still missing and who can fix it, and once nothing is, it says Waiting for your machine to take it. See the Agent row.

1. Create the project

Instance administrator, from Projects → New Project — only an administrator can create one. The quick start covers the fields.

A new board’s default columns already carry the four roles a run needs: To Do is where work is approved, and there is a column for work in progress, one for review and one for done. If you rename or rebuild the columns, keep those roles; a board missing one refuses every run. See Board columns and task fields.

2. Add the people

Instance administrator creates the accounts under Settings → Users. A new account sees no board until it is added to one — the confirmation offers Add to a board for exactly that.

The project’s owner (or an administrator) then decides who is on the board, in the project’s Settings → General, as Owner or Member. Whoever created the project is its first owner. The person who will hand work to their machine only needs to be a member; steps 3 and 4 need an owner. See Members and permissions.

3. Name the repository

Project owner, in the project’s Settings → Integrations → Where the code lives: paste the address you would clone from into Repository URL.

This is what a machine is matched against. Without it no machine can serve the project, the approval page in step 5 has nothing to offer, and a task with an agent chosen says:

This board names no repository, so no machine can match it — the board’s owner can add one in Project settings → Integrations.

The sentence names nobody; to an owner, or an instance admin, it reads you can.

The repository needs a package-lock.json and both a build and a test script, because the shipped agents’ gates run npm ci, npm run build and npm test on every task. See Integrations.

4. Switch agent runs on

Project owner, in the project’s Settings → Workers: turn on Let workers run tasks for this project and save. Until then a task with an agent chosen says:

Agent runs are off for this board — the board’s owner can switch them on in Project settings → Workers.

An owner who approves a machine for this project in step 5 switches it on in the same click, so this step is often already done by then.

An instance administrator can lock workers off for a project, and the lock wins: the owner cannot switch runs on while it is there, and only an administrator can lift it. See Project settings.

5. Connect a machine

The person who will hand work over, on their own Mac. A machine runs only its owner’s work, so the machine has to be yours — not a colleague’s and not the administrator’s. No administrator approval is involved.

1. Get the menubar app. Download the .zip from the latest release, move the app to Applications and open it; see Getting the software.
2. Sign in the tools it drives: claude auth login and gh auth login, with a GitHub account that can push to the repository. Commits carry the GitHub account the app pushes as once you pick one in it (from 1.1.2). With none picked, or on an older worker, git needs a name and address to commit under: git config --global user.email and git config --global user.name.
3. Open the app and fill in its three steps: where the board lives and what to call this machine; the folder it keeps its checkouts in — a folder that holds checkouts, not a checkout; and what this machine has, with the Check this machine button. Connect is offered once every check is green.
4. Approve it in the browser. Connect opens the approval page on the board. Check it shows the same code as the app, choose this project under Which repository should it set up first?, and click Connect it.

The app then clones the repository into the folder, checks it can push to it, and starts the worker. The panel reads Connected and running. The full walkthrough, and the headless route with an enrolment token, are in Setting one up.

Until this is done, your own task with an agent chosen says:

You have no machine connected with this board’s repository checked out. How to connect one

— and, once it is connected, if the machine goes quiet, is paused, or fails a check, the row says that instead. Only you are told about your machines.

Note

The machine should be a Mac. The agent runs inside the macOS sandbox, and a machine without it registers but takes no work unless its owner accepts the risk with CP_ALLOW_UNCONFINED_AGENT=1. See Running the agent unconfined.

6. Choose an agent

Anyone who can edit the task, on the task’s Agent row. Choosing one is the hand-over; a task with no agent is one a person is doing, and no machine looks at it.

Default is the safe first choice: it writes the change, runs every check, pushes a branch and opens a pull request, and merges nothing. A project owner can make one agent the pre-selected choice with Default agent in Settings → Workers, but a task still names its own. See Agents.

7. Assign it to yourself

The person whose machine will run it, on the task’s Assignee row. A machine takes only work its owner assigned to themselves: a task a colleague assigned to you is a proposal, and nothing runs it unattended until you assign it to yourself again. A task with an agent chosen and nobody assigned says:

A machine takes only work its owner assigned to themselves — assign it to yourself.

and one a colleague assigned to you says, with their name:

Ada assigned it, and a machine takes only work its owner assigned to themselves.

8. Move it to the approved column

Anyone who can edit the task: drag it to To Do — whichever column has the approved role on your board. A machine never looks at the backlog, so a task left there with an agent chosen says:

A machine only looks at the column work is approved in — move it there when it is ready.

A task that waits on an unfinished blocker is left alone until the blocker is done, and the row names it.

What happens next

The row now reads Waiting for your machine to take it. Your machine asks for work every 30 seconds, claims the task, and moves it to the column for work in progress. Every step reports back as a comment, so the task’s thread is the run log. With the Default agent the run ends with a pull request and the task in the review column.

If nothing arrives, see A worker polls but never claims anything and Which tasks get picked up.