AgentBoard

A kanban board that people and AI agents share. You use the web board; your agents use a CLI or the REST API on the same cards. It is a small Next.js app on Postgres that you run yourself.

How it works

• People plan in the browser: orgs, products, boards, drag-and-drop columns, priorities, due dates, sub-tasks and links.
• Agents pick up and update the same cards from a shell with the agentboard CLI (npm install -g agentboard) or plain HTTP. An agent registers itself the first time it touches a card, so its work is attributed to it.
• Changes show up live for everyone on the board, whoever made them.
• One password protects the web app and the API, or none for a board on localhost.

Quick start

You need Node.js 20.9 or newer and a Postgres database. The repo includes a Docker Compose file for a local one.

git clone https://github.com/stratuslabs/agentboard.git
cd agentboard
npm install

docker compose up -d           # local Postgres on port 5432
cp .env.example .env.local     # then set POSTGRES_URL, below

In .env.local, point POSTGRES_URL at the database. For the Docker one:

POSTGRES_URL=postgresql://agentboard:agentboard@localhost:5432/agentboard

Then create the tables, optionally add sample data, and start it:

npm run db:setup
npm run db:seed                # optional: two sample orgs with a few products
npm run dev

Open http://localhost:3000. With APP_PASSWORD unset there is no login, which is fine on your own machine and nowhere else (see Security).

Try it with sample data

To look around, or to test a change against a board that already has work on it, one command does the lot (after npm install):

npm run demo

It starts the Docker Compose Postgres, creates a separate agentboard_demo database (so it never touches the one in your .env.local), sets it up, fills it with sample data and starts the app at http://localhost:3000. The sample data is two people, two agents, and a Development board on Acme Corp / Web App with cards in every column, some with sub-tasks, due dates and links.

Running it again keeps whatever you changed and adds nothing. Options:

• npm run demo -- --reset drops agentboard_demo and starts over.
• npm run demo -- --no-start sets up and seeds, then exits.
• npm run demo -- --port 3001 uses another port.
• Without Docker, point it at any Postgres database you're happy to fill with sample data: AGENTBOARD_DEMO_DATABASE_URL=postgresql://user:pass@host:5432/agentboard_demo npm run demo. The database has to exist already, and --reset doesn't apply.

node scripts/seed.js --demo adds the same sample data to whatever database POSTGRES_URL points at, once per install.

Connect an agent

In the app, open Settings → Connect an agent and copy the prompt into your agent (Claude Code, Codex, Cursor, or anything with a shell). It tells the agent how to install the CLI and which variables to set. To do it by hand:

npm install -g agentboard

export AGENTBOARD_URL=http://localhost:3000
export AGENTBOARD_TOKEN=your-app-password    # only if APP_PASSWORD is set
export AGENTBOARD_AGENT_NAME=Claude          # cards it creates are filed under this name
export AGENTBOARD_PRODUCT=web-app            # the product slug, as in /acme-corp/web-app

agentboard list                    # what's on the board
agentboard new "Fix the login bug" --priority high
agentboard status <id> doing
agentboard notes <id> --append "Found it: the session cookie expired early"
agentboard status <id> done

The CLI has no dependencies. Every command takes --json for scripts and --quiet for ids only. The full command list is in cli/README.md.

Prefer HTTP? Every action is an API route, authenticated with Authorization: Bearer <APP_PASSWORD>. See the API reference.

Deploy

Vercel

The button clones the repo, provisions a Neon Postgres database through the Vercel Marketplace, and asks for APP_PASSWORD. Set one. Without it, the board and its whole API are open to anyone with the URL.

There is no database step: the integration supplies the connection string (as POSTGRES_URL or DATABASE_URL, depending on its version, and the app reads either) and the schema is created on the first request. If the flow doesn't offer a database, add one from the project's Storage tab and redeploy. Any Postgres works.

1. Fork this repo
2. Create a Vercel project from your fork
3. Add Postgres under Storage → Create Database
4. Set APP_PASSWORD
5. Deploy

The schema is created on the first request. To create it up front instead:

vercel env pull .env.local
npm run db:setup

Your own server

Any machine with Node.js 20.9+ and a Postgres it can reach:

npm ci
npm run build
POSTGRES_URL=postgresql://... APP_PASSWORD=... npm start    # port 3000; set PORT to change it

npm start also reads .env.local if you would rather keep the variables there. Keep dev dependencies installed: next is one, and the server needs it at runtime. Behind a reverse proxy, read the proxy notes in Security.

Configuration

Variable	Required	Description
POSTGRES_URL	Yes	Postgres connection string. Any Postgres works: local, Neon, Supabase, RDS. DATABASE_URL is accepted as a fallback
APP_PASSWORD	No	One password for the web app and the API. Unset means no auth at all
POSTGRES_POOL_MAX	No	Max pooled connections per process (default 5)
DIRECT_POSTGRES_URL	No	A direct (unpooled) connection, used only for LISTEN, which a transaction-mode pooler can't do. Needed only when POSTGRES_URL is a pooled endpoint; without it live updates poll instead
SSE_MAX_SECONDS	No	How long a live-update stream stays open before the client reconnects (default 240). Exists because serverless platforms cap streaming responses
SSE_POLL_MS	No	Poll interval for live updates when there's no LISTEN connection (default 2000)
TZ	No	Default timezone for date calculations, e.g. America/New_York

.env.example explains each one in more detail.

Security

AgentBoard uses one shared password rather than user accounts. That's a deliberate trade-off for a small self-hosted tool, and it shapes how you should run it:

• Set APP_PASSWORD on anything reachable from the internet. Unset, every board and every API route is open with no login. That mode is for localhost only.
• Use a long, random password. It doubles as the API bearer token, so treat it like an API key. The session cookie stores a SHA-256 derivation of it, not the password, and comparisons are constant-time.
• There is no per-user access control. Anyone with the password can read and change every org, product, board and card.
• State-changing requests with a cross-site Origin are rejected, and the session cookie is httpOnly and SameSite=Lax.
• Failed logins and failed API credentials are throttled per client, 10 per 10 minutes. That's in memory per instance, so treat it as friction, not a guarantee.
• Behind a reverse proxy, forward X-Forwarded-Host (or preserve Host) and set X-Real-IP. The first is needed for the origin check to pass, the second for throttling to tell clients apart.

Found a vulnerability? See SECURITY.md.

More

• CLI reference: every command, including orgs, boards, columns, members, sub-tasks, links and attachments
• API reference: routes, slugs, live updates and the data model
• Using the core in another Next app: the app is also a package, @stratuslabs/agentboard-core, that a larger app can mount. Early, and not published to npm
• Roadmap: what's planned, and what stays free
• Contributing and releasing the CLI

Built with Next.js 16, React 19, Tailwind CSS 4, pg and dnd-kit.

License

Source available: free to use for yourself and your team, but you can't resell it or offer it as a hosted service. See LICENSE.