Troubleshooting
Real failure modes and their real fixes. Two habits solve most of what goes
wrong: read the machine's own log (~/.meshboard/agent.log — the agent says
what's wrong in plain words), and re-run your account's installer command
from Mesh → Add a machine — it's idempotent, takes a few seconds, and
restarts the agent with a fresh pairing.
Symptom → fix
| Symptom | Fix |
|---|---|
| The install finished but the machine never appears | Pairing didn't complete — usually an expired install command (they're single-use and expire after about thirty minutes). Check the last lines of ~/.meshboard/agent.log, then mint a fresh command from Mesh → Add a machine and run it again. |
| Asks fail with an AI account error | The account on that machine signed out. codex login or claude setup-token on the machine, and the mesh picks it back up. |
| A task sits in open and never moves | Usually no connected AI can take it. On the machine you expect to work it, check ~/.meshboard/agent.log — no coding launchers detected names the blocker; Connect your AI is the fix. |
| A machine shows stale or offline | Restart the agent: macOS launchctl kickstart -k gui/$(id -u)/ai.meshboard.agent · Linux systemctl --user restart meshboard-agent · Windows re-run the installer command. If in doubt on any platform, re-running the installer is the safe universal repair. |
| Everything looks healthy but behaves stale | The agent may be running old code after an update — restart it (same commands as above). |
Reading a machine's own account of itself
tail -n 50 ~/.meshboard/agent.log
The log is the agent narrating: enrollment, what AI it detected, every poll, every dispatch. It's written for humans — most problems name themselves in the last ten lines.
The phone app
The MeshBoard phone app is in beta. If you're in the beta and pairing misbehaves, the app's own screens carry the current repair steps — the browser at app.meshboard.ai is always the fallback and can do everything the phone can.
Still stuck?
Every route to a human is on the support page. From inside the app, Settings → Send feedback files straight to a person's board with your device context attached — you don't need to reproduce logs by hand.