Troubleshooting

Each entry says what you see, why, and what to do.

You see: a setup wizard the first time you start, Set up a harness on the dashboard, or a Not installed card in Settings → Harnesses. Starting a session says the harness isn’t installed.

Why: Fleet doesn’t include a harness. It looks for the program in its own folder and on your PATH.

Fix: choose Set up a harness and install one, or install it in a terminal and choose Check again. Choose a harness has the steps for each. Pi is the exception: Fleet can’t install it, so install it from pi.dev first.

Why: the harness is installed but you haven’t signed in.

Fix: use the sign-in panel on its card. For Claude Code, run claude auth login. For GitHub Copilot, choose Sign in with GitHub. For Pi, sign in inside Pi. Then choose Check again. OpenCode 2 doesn’t reuse OpenCode 1’s sign-ins, so sign in again there.

Why: the version is older than Fleet supports (OpenCode 2 needs 2.0.6, OpenCode 1 needs 1.15.10), or the program fails to start.

Fix: update it from its card. Claude Code has an update button there. Then choose Check again.

Why: Fleet’s opencode found on your PATH is OpenCode 2, or the other way round. The card says so.

Fix: install OpenCode 2 In its own folder so it keeps its own settings and sign-ins. As your main opencode replaces OpenCode 1.

Why: the installers aren’t signed yet, so your system warns about them.

Fix:

• macOS: open System Settings → Privacy & Security and choose Open Anyway.
• Windows: when SmartScreen says it protected your PC, choose More info → Run anyway.
• Linux AppImage: needs FUSE 2 (libfuse2).

See Install.

Why: only one Fleet can use a data folder (~/.weave) at a time. The message names the other Fleet’s address.

Fix: use that Fleet, or quit it first. The desktop app connects to a Fleet that is already running instead of starting a second one. To run two on purpose, give the second its own data folder with --data-dir.

Why: once Fleet listens on a network address, or runs with --require-token, every request needs the access token.

Fix: open the /login?token=… link Fleet prints when it starts. Find the token again in Settings → Machines → This machine. See Security and access.

Why: the token was replaced on that machine, or you pasted it wrong.

Fix: copy the current token from that machine’s Settings → Machines → This machine and paste it again in Add a machine.

Why: the machine is off, asleep, on another network, or the address is wrong. A page on https:// also can’t call an http:// machine.

Fix: check that Fleet is running there and that you can open its address in a browser. Use an HTTPS address if you’re on one. See More machines.

Fix: open Fleet from the Home Screen icon on iPhone, check the bell and Send a test notification, and check the home machine is running. If the phone offers no install option, the page isn’t HTTPS. Use the tailscale serve address. An expired QR code needs a new one. See Fleet on your phone.

• Install: get Fleet running.
• Choose a harness: set up the coding tool.
• Security and access: tokens and pairing.