Fix common problems

Each problem below is headed by the exact text the board shows, so pasting an error into the docs search lands here. The last sections cover what to do when you need everything to stop, how to restart the board, and where each kind of install writes its logs.

Starting and signing in

Refusing to start: binding to a non-loopback host

The board was started on an address other people can reach (such as 0.0.0.0 or a LAN address) with no access token. Anyone who reaches it could run agents, and so shell commands, on your machine, so it refuses.

Fix: set a token, then start it again.

export REV0_AUTH_TOKEN="$(python3 -c 'import secrets;print(secrets.token_urlsafe(32))')"

To keep it, add the REV0_AUTH_TOKEN=... line to ~/.rev0/.env. The one-line installer and the desktop app already create one. Binding with no token on purpose needs REV0_ALLOW_INSECURE=1, which only makes sense on an isolated network.

auth required

A request reached a board that has an access token, without the token. In a browser you land on the sign in page instead.

Fix: sign in. Paste the token where it says Paste your REV0_AUTH_TOKEN and click Sign in. On a board you are already signed in to, Settings > Security > Access token copies it. A script or the CLI sends it as an Authorization: Bearer header.

Incorrect token. Try again.

The token you pasted is not the one the board runs with. The board reads REV0_AUTH_TOKEN from its environment first, then from ~/.rev0/.env. The one-line installer writes it to the .env of its checkout (~/rev0/.env), which the board copies into ~/.rev0/.env on its first start. If you changed one of them later, they may disagree: use the value the running board has, or set the same value in both and restart.

this action must be initiated from a logged-in browser session

Some actions (such as trusting a plugin, installing a browser extension or writing to the App Space) are refused to a token sent by a script, the CLI or an agent. Do them in the board, in a browser where you signed in.

rev0 could not start the board

The Windows app shows this when the board did not come up inside WSL. In order of likelihood:

WSL is not set up. Run wsl --install in PowerShell, restart Windows, open Ubuntu once to create your Linux user, then open rev0 again.
Your default distro is WSL 1. wsl -l -v shows the version; wsl --set-version with the distro’s name and 2 converts it.
localhost forwarding is off. The window reaches the board over WSL’s localhost. If .wslconfig in your Windows home sets localhostForwarding=false, remove that line and restart WSL.

The board’s own logs are inside WSL, in ~/.local/state/rev0.

Agents that do not run

The agent CLI’s login expired or was never made on this machine. The same message names Codex or Cursor when their CLI is the one signed out.

Fix: open Settings > Agents, click Sign in (or Re-authenticate) in Claude auth, Codex auth or Cursor auth, and approve on the page it links. Tickets parked by this go back to To Do on their own once the login succeeds. The panels, and how to sign in from another device, are in Run Codex or Cursor instead of Claude Code.

codex CLI is not logged in

Codex is signed out. Sign in from Settings > Agents > Codex auth, or run codex login on the board’s machine. The Cursor version, Cursor CLI is not logged in; sign in from Settings, is fixed the same way in Cursor auth.

codex engine selected but the `codex` CLI is not on PATH

The ticket’s model runs on Codex, but the board cannot find codex. Install it with npm install -g @openai/codex, then sign in. In the desktop app, a CLI you installed after opening the app is found once you quit and reopen it.

Cannot start this run: the kanban MCP server failed to start

The board’s own tools for agents could not start, usually because a source install’s environment is missing a package. Run uv sync in the rev0 checkout, restart the board, then move the ticket back to To Do.

A ticket stays In Progress and nothing happens

Open it and look at the timeline:

the agent CLI sent no output for 300s while waiting on the model API: the model API stalled. The board retries this on its own a few times, resuming the saved session.
Nothing new for a long time: click Stop agent in the ticket’s … menu. The ticket moves to Pending Action with its session kept, so moving it back to To Do resumes where it stopped.
The board was restarted mid run: on its next poll the runner notices the orphaned ticket and queues it again from its last saved session.

If no ticket in To Do ever starts, check that the board runs with its runner (serve --with-runner, which the installer, the app and Docker all do), that Max concurrent agents in Settings > Workspace > Board is not full of other running tickets, and that the board was not paused with Agents can run tickets on this board (the switcher then says agents off).

Hit a Claude usage limit

Your Claude plan’s usage window is full. The board parks the ticket and resumes it on its own when the window resets. See Track usage and cap spend.

Spend ceiling reached

A spend budget you turned on was reached, so the next turn did not start. See Track usage and cap spend.

could not create an isolated git worktree

The board could not make the ticket’s worktree, often because an old one is still registered at the same path. It refuses to run in your own checkout instead. Run the command the message suggests in the repository (git worktree remove --force <path> && git worktree prune), then move the ticket back to To Do.

Merging

Waiting to merge

The base branch’s checkout has uncommitted changes to tracked files, so the board will not merge into it. The ticket’s timeline lists the files. Untracked files do not block it.

Fix: commit or stash those changes in your own checkout of the base branch. The board retries on its own; after about ten tries it parks the ticket in Pending Action, and moving it back to In Review retries the merge. More in Review and merge an agent’s work.

that could not be auto-resolved

A merge hit conflicts that the agent could not resolve in two tries. The branch and worktree are kept. Move the ticket back to To Do so the agent resolves them and finishes again, or follow Resolve a merge conflict.

python coverage 0.0% is below the 80% floor

The code quality gate measured no coverage for your new Python files, even though their tests pass. On a board run from source, the gate runs the repository’s tests with the board’s own Python, which cannot import packages installed only in the repository’s own virtual environment. The tests then fail to load, and every file reads 0% (a CRAP score with coverage 0% is the same problem).

Fix, one of:

On that ticket, click Override quality gate in Verification checks to accept this branch without the gate.
For a board that works on such a repository, turn off Pre-merge gate with a per-board override (Board settings…, then Per-board overrides).
Run the board from the binary or the desktop app, which run the tests with uv run in the repository’s own environment.

The gate itself is in Hold agents to a quality bar.

Stop every agent at once

Emergency stop halts everything in one click: it asks every running agent to stop, kills every background task, and pauses agents on every board so nothing new starts.

Turn on Debug tools in Settings > Automation > Debug, and click Save changes (the Maintainer profile has it on).
Open Settings > Advanced. In Emergency stop, click Emergency stop and confirm.

Result: running tickets stop, and every board shows agents off. To start again, click Re-arm in the same section: it lets agents back on the boards it paused. Stopped tickets do not restart on their own; move the ones you want back to To Do.

To stop one ticket instead, click Stop agent in its … menu. To keep agents off one board, clear Agents can run tickets on this board in its Board settings….

Restart the server

A restart interrupts running agents, which resume from their saved session once the board is back.

From the board: turn on Debug tools (Settings > Automation > Debug), then click Restart server in Settings > Advanced > Board & debug. On a source install with an update waiting, Settings > Advanced > Updates has the same button.
Desktop app: Quit rev0 (Cmd+Q or Ctrl+Q), then open it again.
In a terminal (installer, source or binary): press Ctrl+C, then run the same command again, such as uv run -m rev0.cli serve --with-runner.
As a systemd --user service (the installer with INSTALL_SERVICE=1): systemctl --user restart rev0.
Docker: docker compose restart.

Restart server restarts with the same environment, so after changing a value in a .env file, stop and start the board instead.

Where the logs are

Install	Logs
One-line installer or source, in a terminal	The terminal that runs the board.
One-line installer as a service	`journalctl --user -u rev0 -f`
Docker	`docker compose logs -f`
Binary	The terminal that runs `serve`.
macOS app	`~/Library/Logs/rev0`: `server.log` for the board, `rev0.log` for the app. Show logs in the menu bar icon opens the folder.
Linux app	`~/.local/state/rev0` (`$XDG_STATE_HOME/rev0` if you set it), same files. Show logs in the tray menu opens it.

On every install, what an agent did is on its ticket’s timeline, a background task’s output is in ~/.rev0/background_jobs, and ~/.rev0/runner-stalls.log records anything that held up the runner for every ticket at once.

Install rev0, to reinstall or update.
Back up and restore the board, before you try anything drastic.
Answer what the board asks you, for tickets parked on purpose.