agent-board-runner 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# agent-board-runner
+
+Local runner for [Agent Board](https://github.com/paulaolileal/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.
+
+```sh
+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](https://pm2.keymetrics.io/) 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`](https://github.com/cloudflare/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.