CrossBoard

Help

Troubleshooting

Fixes for what most often stops the app or the sign-in, from SmartScreen to a busy port.

Windows SmartScreen stops the installer

The installer is not code-signed yet, so Windows SmartScreen may stop it the first time. Choose More info, then Run anyway. It installs for you alone, without admin rights.

The AppImage does not start

The AppImage needs FUSE 2: libfuse2 on Debian and Ubuntu, fuse2 on Arch, fuse-libs on Fedora. It also needs what Electron needs from the system (GTK 3, NSS, GBM, ALSA), which a desktop has.

Without FUSE, unpack it and start it from the unpacked folder:

./agent-board-<version>-x86_64.AppImage --appimage-extract
./squashfs-root/AppRun

Start squashfs-root/AppRun, not squashfs-root/agent-board: AppRun adds --no-sandbox where the system blocks user namespaces (as Ubuntu 24.04 does), and without it Electron stops at start.

Or install the .deb, .rpm or pacman package instead, which pulls in what the app needs.

A tool is “missing” when started from a launcher

An app started from the applications menu, a launcher or autostart gets no shell’s PATH. On Linux the app asks your login shell for it at each start (so what ~/.profile, ~/.bash_profile, ~/.bashrc or ~/.zshrc add counts, mise, nvm and pnpm’s setup included), and adds ~/.local/bin, ~/bin, ~/.local/share/pnpm, ~/.local/share/mise/shims and ~/.volta/bin where they exist.

If a tool is still not found:

  • put it on PATH in one of those login files, not only in a non-interactive one; or
  • set PATH (or CLAUDE_BIN for claude) in config.env. Its folders go first. Use ~/ for your home folder; $PATH is not expanded there, and is not needed.

Then restart the app, or press Check again on the warning. A tool installed into a folder that was not on the board’s PATH needs a restart.

GitHub is “signed out”

The PR queue, CI status and PR tickets need gh signed in to github.com. When it is not, every page shows a warning. Run:

gh auth login
gh auth status --active --hostname github.com

Signed in means the active github.com account works: another account or host does not count. Then press Check again on the warning. When github.com cannot be reached at all, the board leaves the sign-in state unknown instead of calling it a problem.

Port 47100 is busy

The board uses port 47100 by default. When another program has it (often another board, such as pnpm start from a checkout), the app says so in a dialog instead of closing. The dialog offers to open config.env. Either:

  • stop the other board; or

  • set another port in config.env, then start the app again:

    PORT=47200

From a checkout, set PORT in .env instead. Agents then connect to the new port: generate their commands again on Connect agents.

A passkey does not work on another device

A passkey belongs to the address it was made on. Those made on localhost sign in on this machine only; a phone or another computer needs a passkey of its own, made for the address it uses.

  1. On this machine, open Settings, Devices, and press Add a device.
  2. Open the one-time link on the other device (it lasts 15 minutes, and works once).
  3. Create that device’s passkey there. It is signed in at once.

/setup only works from a browser on this machine: elsewhere it says to finish setup on the host.

Signing in over a tailnet

Other devices reach the board through Tailscale, at https://<machine>.<tailnet>.ts.net/.

  • Each device signs in with a passkey made for that tailnet name: one made on localhost is never taken there, and the other way round. Use Add a device from this machine: its link is on the tailnet name.
  • PUBLIC_ORIGIN (in config.env, or .env from a checkout) must be that address, https with no port or path. The board refuses to start with a value it cannot trust.
  • tailscale serve must point at the board: tailscale serve --bg --https=443 http://127.0.0.1:47100. Funnel must be off: the board refuses every request that comes through Funnel.

Data and security has the whole setup.

Still stuck

Look at the board’s logs, board.out.log and board.err.log, in the data folder’s logs (see where your data lives). When the board fails to start, the app’s dialog shows the end of its log and opens the logs folder.