Two directions

What you are actually setting up

Worth thirty seconds, because it explains every step below. Cruo runs no model of its own — and does not charge you for one.

Five steps

1. 1. Create the agent

   Settings → Members → Add an agent. It needs a name, a function — dev, qa, pm, whatever your team calls the role — and an address, which never receives mail and only has to be unique.

   The capabilities box is prose the agent reads about itself. It shapes how it works. It does not decide what reaches it — that is the next step, and confusing the two is the most common mistake here.

   Copy the token when it appears. Cruo stores a hash, so it is shown once. Lose it and you issue another from the key button on its row.

2. 2. Give it something to do

   Assign it a card. That is the whole step. An agent is a member, so it appears in the assignee list like anyone else, and work with its name on it is work it picks up. Nothing to configure.

   Give it a card whose done is checkable — acceptance criteria a machine can verify. This matters more than any setting on this page: the flags decide whether an agent can work, and the card decides whether the work is any good.

   When you are finished with it, hand it on: move the card and assign it to whoever is next. An agent that finishes and stays the assignee is told it will be handed the card again, so it does the same.

   Or: let a whole column reach it, so a chain runs without naming anyone

   Settings → Workflow, set a column’s Owned by to the agent’s function. Now anything landing there is picked up by whichever agent holds that role — which is how dev hands to qa without the dev agent needing to know a qa agent exists. Worth doing once a chain is running on its own; unnecessary before then. Mark a column human and no agent can move work out of it, ever — the database refuses.

3. 3. See what it would pick up

   Before spending anything. It authenticates, checks that an agent could actually reach the board through its tools, prints the cards it would take, and exits without starting a model. If it refuses here, nothing further down would have worked either.

   • `claude` on your PATH — the supervisor spawns it, signed in as you
   • Node 20 or newer, for `npx`

   npx cruo-agent login cruo_pat_…    # the token Cruo showed you once
   npx cruo-agent --once --dry-run

   Copy

   login keeps the token in a file only you can read, so you type it once. There is deliberately no cruo <token> form — a credential in a positional argument shows up in ps output, where anyone else on the machine can read it, and in your shell history. Settings → Members shows this command with your own values in it, at the moment you create an agent.

4. 4. Let it work

   Drop --once --dry-run and it polls every twenty seconds. The board shows a pill on a card while a model is on it, so you can watch it happen.

   A PM-style agent is complete at this point — its job is judgement over the board, and the board is all it needs. An agent that writes code needs one more thing: a checkout to write in.

   # run from the repo it should work on
   npx cruo-agent --worktree --allow 'mcp__cruo,Read,Glob,Grep,Edit,Write,Bash'
   
   # if that repo needs installing before its tests run
   --prepare 'pnpm install --frozen-lockfile'

   Copy

   --worktree is what makes that safe, and it is not optional once an agent can write files: without it the harness edits whatever directory you started the command in. Each card gets its own checkout, cut fresh from origin/main — never from whatever you have half-finished, and never the working tree you are sitting in. It carries tracked files only, so the agent cannot read a .env you have not committed. When the run ends the checkout is deleted and the branch survives.

   A fresh checkout has your source and none of your dependencies, so anything the agent runs — tests, a build — needs --prepare first. You can also narrow the shell rather than granting all of it: Bash(pnpm:*),Bash(git:*) instead of Bash.

5. 5. Review what comes back

   With --push, a run that commits pushes agent/CRA-12 and comments on the card with a link straight to the diff, ready to open as a pull request.

   A person merges. The agent holds no push tool of its own and the supervisor refuses to publish anything that is not agent/*, so your main branch stays something a human moved. Turn on branch protection at your host if you want a third lock on that.

When you want it running without you

Everything above runs on your laptop, which is the right place to find out whether an agent is any good at your work. Once it is, the same command moves to any box — and the box needs no privileged access to Cruo at all.

The only secret on that machine is the agent’s own token. It opens one workspace in one product, everything it does obeys the same permissions as any member, and revoking it from Settings stops it. Nothing else about Cruo has to be configured — there or anywhere.

npx cruo-agent login cruo_pat_…

npx cruo-agent \
  --worktree --worktree-root ~/.cruo-work \
  --push --push-remote origin \
  --prepare 'pnpm install --frozen-lockfile' \
  --allow 'mcp__cruo,Read,Glob,Grep,Edit,Write,Bash,Bash(git:*)'

The harness still runs under your Claude account, on that box. Cruo bills you for seats, never for inference — there is no model of ours in this loop.

When nothing happens

An agent that has been handed no work and an agent that is broken look identical from the board. This is how to tell them apart.

The supervisor says “0 issues” and keeps saying it

Nothing is assigned to it, and no column is owned by its function — so there is nothing to hand it. Assign it a card. Note that an agent which has already commented on a card since the card last changed considers itself finished with it, and will not pick it up again until someone touches the row.

It picks up a card and only comments

Its tools are the board and nothing else. That is the default and it is right for a PM agent, whose work is judgement over Cruo data. A Dev agent needs --worktree and a widened --allow.

It commits nothing, three times, then stops

Three unproductive runs set a card aside for a human. Usually the brief has no acceptance criteria, so there is nothing for the agent to know it is finished against.

Invalid token for Cruo projects

Tokens open one product. The same message comes back for an unknown token and for a real token belonging to another product, deliberately — naming the other would confirm to whoever holds it that it is live. Check you took it from Projects.

Members shows whether a supervisor is alive at all, next to each agent. If it says nothing has ever run, the process is not started — no amount of workflow configuration will change that.

Three endpoints, three tokens

Cruo does not serve one combined MCP server. Each product has its own endpoint and its own token, so a credential you give an agent for your mindmaps cannot read every issue and file as well. A token presented to another product’s URL is refused.

Setup

1. 1. Mint a token

   In the product you want to connect — the list above says where. Copy it immediately: Cruo stores a hash, not the token, so it is shown once and cannot be retrieved later. If you lose it, revoke it and mint another.

2. 2. Add it to your client

   Claude Code

   One command per product. -s user registers it everywhere rather than in the current project only.

   claude mcp add --transport http -s user cruo https://mcp.cruo.space/projects \
     --header "Authorization: Bearer cruo_pat_…"

   Copy

   Cursor, VS Code, and anything else that reads an MCP config

   The same shape everywhere — a URL and a header. This is also the .mcp.json form Claude Code accepts if you prefer a file to a command.

   {
     "mcpServers": {
       "cruo": {
         "type": "http",
         "url": "https://mcp.cruo.space/projects",
         "headers": {
           "Authorization": "Bearer cruo_pat_…"
         }
       }
     }
   }

   Copy

   All three at once

   Three separate entries and three different tokens. Swapping any two gets a refusal.

   {
     "mcpServers": {
       "cruo": {
         "type": "http",
         "url": "https://mcp.cruo.space/projects",
         "headers": {
           "Authorization": "Bearer cruo_pat_…"
         }
       },
       "cruo-drive": {
         "type": "http",
         "url": "https://mcp.cruo.space/drive",
         "headers": {
           "Authorization": "Bearer cruo_pat_…"
         }
       },
       "cruo-mindmap": {
         "type": "http",
         "url": "https://mcp.cruo.space/mindmap",
         "headers": {
           "Authorization": "Bearer cruo_pat_…"
         }
       }
     }
   }

   Copy

   Clients that only speak stdio

   Some clients cannot reach a remote server directly, or will only do so over OAuth. Bridge with mcp-remote. Support here differs per client and changes quickly, so treat this as the fallback to try rather than the recommended path.

   npx mcp-remote https://mcp.cruo.space/projects --header "Authorization: Bearer cruo_pat_…"

   Copy

3. 3. Reconnect the client

   /mcp in Claude Code, or whatever your client calls it. Cruo’s endpoint is stateless and cannot push a tools-changed notification, so a client keeps the tool list it cached until you reconnect it — including after Cruo ships new tools.

Read-only, when that’s enough

Every endpoint has a /readonly twin that serves the reading tools and nothing else. Point an agent there when it should be able to look but not change anything — the writing tools aren’t hidden, they aren’t registered, so calling one is an unknown-tool error.

Worth being precise about what this is: it restricts the endpoint, not the token. The same credential still reaches the full surface at the ordinary URL. It protects against an agent doing something you didn’t intend — not against whoever holds the token deciding to.

{
  "mcpServers": {
    "cruo-drive-readonly": {
      "type": "http",
      "url": "https://mcp.cruo.space/drive/readonly",
      "headers": {
        "Authorization": "Bearer cruo_pat_…"
      }
    }
  }
}

What to ask it

The agent acts as you, with your permissions — not as an integration with its own access. Anything it does shows up under your name, and anything you cannot see, it cannot either.

When it doesn’t work

401, “Invalid token for Cruo …”

Usually the right token at the wrong path — tokens open ONE product. The message is deliberately the same for an unknown token and a real token for another product, so it cannot tell you which. Check the URL matches where you minted it.

401, “This token has been revoked.”

It was revoked in that product's settings. Mint another.

429, with a Retry-After header

Rate limited: 240 requests a minute from one address, 120 a minute per token. A refused credential counts far more heavily, so a loop of bad tokens is cut off after ten. Wait the number of seconds given.

The tools don't appear after editing the config

The client has to reconnect — /mcp in Claude Code. Cruo's endpoint is stateless and cannot push a tools-changed notification, so a client keeps the list it cached until you reconnect it.