CrossBoard

Help

Data and security

Where the board keeps your data and settings, how to back up, upgrade and uninstall, how sign-in works, and how to report a vulnerability.

Where your data lives

Everything stays on your machine: one SQLite database, the uploaded files, the logs, and the settings.

Windows: %LOCALAPPDATA%\agent-board

  • data\: the database, uploads and logs (data\logs\board.out.log, board.err.log).
  • config.env: the settings.
  • electron\: the app window’s browser profile (its sign-in, its cache).

Linux (following XDG_CONFIG_HOME and XDG_DATA_HOME when they are set):

  • ~/.config/agent-board/config.env: the settings.
  • ~/.config/agent-board/electron/: the app window’s browser profile.
  • ~/.local/share/agent-board/data/: the database, uploads and logs.

From a checkout: data/ in the checkout, and the settings in .env.

AGENT_BOARD_HOME in the environment puts all of them in one folder of your choice.

Settings in config.env

config.env holds KEY=value lines, read at each start. The first start writes it with every key commented out:

  • PORT: the board’s port, 47100 by default.
  • DATA_DIR: the data folder, anywhere you like (a relative path is under the app’s folder).
  • CLAUDE_BIN: where claude is, when it is not on PATH.
  • PUBLIC_ORIGIN: the board’s address on your tailnet (below).

A variable set in the environment wins over the file. The app always runs in production on 127.0.0.1.

Backups

To back up the board, quit the app (tray menu, Quit, which stops the board) and copy the data folder, data above, with config.env. Restore by putting them back before the app starts.

Previews and runs never touch your real data when they copy it: a run that asks for the live data gets a fresh copy in its worktree’s data/preview, made through SQLite’s backup, and what you do in a preview stays in that copy.

Upgrading

The app does not update itself. Download the newer build and install it over the old one (the AppImage: replace the file). Your data and settings are kept.

From a checkout: pnpm stop, git pull, pnpm start. It installs dependencies and applies database migrations as it starts.

Uninstalling

Uninstalling leaves your data and settings in place.

  • Windows: Settings, Apps, CrossBoard, Uninstall. Then delete %LOCALAPPDATA%\agent-board to remove the data and settings too.
  • Linux: sudo apt remove agent-board, sudo dnf remove agent-board (zypper remove on openSUSE) or sudo pacman -R agent-board; the AppImage: delete it. Then delete ~/.config/agent-board and ~/.local/share/agent-board (and ~/.config/autostart/agent-board.desktop, if Start at login was on).

Signing in

  • You sign in with a passkey at /login. Your first visit, on this machine, goes to /setup, which makes the one account and its first passkey.
  • A session lasts 90 days. Settings, Devices lists your passkeys and the sessions they opened, each revocable, and has Sign out. The last passkey of this machine cannot be revoked, so you are never locked out.
  • Agents never sign in with a passkey: each sends Authorization: Bearer <token> with a token from Connect agents. A token is shown once, signs in for a year, and can be revoked there.
  • Nothing secret is kept in plain text: sessions, device links and tokens are stored as SHA-256 hashes.

Using it from other devices

The board opens on your phone, tablet or another computer through your Tailscale tailnet, over HTTPS at https://<machine>.<tailnet>.ts.net/. It is off until you set it up.

Before you start: Tailscale on this machine and each device, signed in to the same tailnet; MagicDNS and HTTPS certificates turned on in the Tailscale admin console; and access rules that let only your own devices reach this machine on 443.

  1. Set PUBLIC_ORIGIN=https://<machine>.<tailnet>.ts.net in config.env (or .env), then restart the board.
  2. Point Tailscale at the board: tailscale serve --bg --https=443 http://127.0.0.1:47100. From a checkout, pnpm tailnet prints the command for this machine.
  3. Give each device a passkey: Settings, Devices, Add a device on this machine, then open the link on the device.
  4. Open https://<machine>.<tailnet>.ts.net/ on the device.

Agents on other devices connect to https://<machine>.<tailnet>.ts.net/api/mcp with their token.

What holds: the board still listens on 127.0.0.1 only; it refuses every request that comes through Funnel; nothing answers without a session or a token but the sign-in pages; and previews stay on this machine. To close it, run tailscale serve --https=443 off and remove PUBLIC_ORIGIN.

Reporting a vulnerability

Report a vulnerability privately, through GitHub’s private vulnerability reporting: github.com/nervesscat/agent-board/security/advisories/new (the repository’s Security tab, Report a vulnerability). Only the maintainers see it.

  • Do not open a public issue, discussion or pull request about it, and do not post details elsewhere until a fix is released.
  • Say what is affected (version or commit, the Windows or Linux app or a checkout), how to reproduce it, and what an attacker gains. Keep any proof of concept to your own installation.
  • Do not test against boards that are not yours.

You get an acknowledgement within 7 days and an assessment within 14. An accepted report gets a fix in a new release and a GitHub security advisory crediting you, unless you prefer not to be named. Only the latest release and the default branch get security fixes.

Security scope

In scope: the board’s server and pages, its sign-in (passkeys, sessions, agent tokens), its REST API and MCP server, the desktop app and its installers, and the scripts in its repository.

Out of scope: a board deliberately run with its sign-in off (test mode, which only runs on loopback outside production), what a signed-in human or an agent with a valid token may do by design, and flaws in git, gh, claude or other tools the board starts (report those to their projects).