agent-board-runner

Local runner for Agent Board: watches your projects' board for cards, runs Claude Code against your own repos on your own machine, and exposes a terminal/preview back to the web app over a Cloudflare Quick Tunnel — no Cloudflare account, login or setup required; start opens it for you and it just works.

Signs in with your own Google account (Supabase Auth) — there's no shared secret to be handed out. Every read/write it makes is scoped to your account by the database's row-level security, same as the web app.

Install and run

No .env file needed for the default setup.

npx agent-board-runner login
npx agent-board-runner start --path /path/to/your/repos

• login opens your browser to sign in with Google. The session is saved locally (~/.agent-board/session.json) and refreshes itself automatically — you only need to do this again after an explicit logout, even across restarts.
• start --path <folder> runs the runner, pointed at the local folder that holds your repos (every project's repo lives somewhere under it). --path can be skipped once AGENT_BOARD_ALLOWED_ROOT is set instead (see below) — either way it only needs setting once; the runner remembers it across restarts. Keep start running while you work — it's what actually picks up card moves and drives Claude Code. For something that survives closing the terminal, run it under pm2 or your OS's service manager instead of a plain foreground process.
• Projects themselves are never registered from the CLI — add, edit and remove them from the web app's "Adicionar projeto", picking a subfolder under the repos root above. Any project pointing at this runner's id is picked up automatically on the next tick.

Other commands: whoami (show the signed-in account), logout (clear the local session).

Optional environment variables

Only needed to override the defaults — see .env.example.

• AGENT_BOARD_SUPABASE_URL / AGENT_BOARD_SUPABASE_ANON_KEY — point the runner at your own Supabase project instead of the shared default.
• AGENT_BOARD_RUNNER_NAME — defaults to your machine's hostname.
• AGENT_BOARD_ALLOWED_ROOT — the local folder that holds your repos; alternative to start --path (which takes priority if both are set). Required one way or the other — every project's repo path is resolved relative to it, and it's also what the web app's "add project" folder browser lists.
• AGENT_BOARD_TERMINAL_PORT — local port for the terminal/files HTTP server (default 8787).

Requirements

• Node.js 18+.
• cloudflared is downloaded automatically on first use if it isn't already on your PATH. No Cloudflare account is needed: the runner always opens an anonymous Quick Tunnel (*.trycloudflare.com), never a named/authenticated one. Its hostname changes every restart — the web app always reads the current one from runners.tunnel_hostname, so this needs no attention from you.
• node-pty is a native module — if npm install fails building it, install your platform's usual native build toolchain (e.g. build-essential/Xcode Command Line Tools/Visual Studio Build Tools) and retry.

Known limitation: OAuth login inside a review preview

Moving a card into "revisao" tunnels that project's own dev server through its own Quick Tunnel, with a fresh random *.trycloudflare.com subdomain every time. If the project you're reviewing signs in through a hosted auth provider (Supabase Auth, Auth0, etc.), the post-login redirect will likely bounce back to localhost instead of the tunnel URL — the new subdomain was never allow-listed with that provider.

Fix it once per project, in that project's own auth provider (not in Agent Board): add a wildcard entry to its redirect URL allow list, e.g. on Supabase, Authentication > URL Configuration > Additional Redirect URLs > https://*.trycloudflare.com/**. Providers without wildcard support in that allow list (e.g. Firebase Auth) don't have an equivalent fix without extra infrastructure.