Set up from zero
This page takes a computer with nothing installed to a clone of Andon whose checks pass. Do it once. After that,
Local development covers the daily loop: pnpm dev and pnpm dev:demo.
What you need
Install what your work needs. Node, pnpm and git are enough to run the board and the unit tests.
| Tool | Version | Needed for |
|---|---|---|
| Node | 22 (.nvmrc; package.json says >=22) |
everything |
| pnpm | 10 (packageManager pins 10.34.1; corepack enable picks it up) |
everything |
| git | any recent | everything; the agent’s tests build real repositories |
| Docker, or colima on macOS | any recent | only the container checks: the Linux install test in agent-int (skip it with ANDON_SKIP_DOCKER=1) and scripts/compose-smoke.sh |
| tmux | 3.x | the agent-int suite and pnpm dev --agent |
| ffmpeg | any recent | the agent-int suite (output previews) |
| Playwright browsers | the version the board pins | the e2e suite: pnpm --filter @andon/board exec playwright install chromium webkit |
Rust (rustup) |
stable | the desktop app only; on macOS also the Xcode command line tools, on Linux the webkit2gtk packages Tauri lists |
GitHub CLI (gh) |
any recent | opening pull requests; the agent’s fake gh covers the tests |
You don’t need a Postgres install. pnpm db:local runs an embedded Postgres 17 per checkout, with no Docker.
On macOS with Homebrew, the whole list is:
brew install node@22 pnpm git colima docker tmux ffmpeg gh rustupcolima startOn Debian or Ubuntu, sudo apt-get install -y tmux ffmpeg git, Node 22 from your usual source, and Docker Engine.
Clone and build
-
Clone the repository and install the dependencies:
shell git clone https://github.com/psci-labs/andon && cd andonpnpm install -
Build the two packages every other package imports. The unit tests fail with
Failed to resolve entry for package "@andon/shared"until you do:shell pnpm --filter @andon/shared --filter @andon/client build -
Run the fast checks. None of them needs a database:
shell pnpm typecheckpnpm lintpnpm check:personalpnpm check:docspnpm exec vitest run --project board --project agent --project @andon/shared -
Start the app with
pnpm devand open the address it prints. The first run seeds a demo org and writes its logins to.env.local. Local development says what elsepnpm devcan do.
Configuration
pnpm dev reads .env.local (git-ignored) and writes the server’s ANDON_SECRET_KEY there on its first run. Add a
line to it only when you need a key: a Gemini or AI Gateway key for the assistant and attention triage, a GitHub OAuth app for sign-in
with GitHub, and so on. .env.example names every key with a placeholder, and
Environment variables says what each one does.
Never commit a real email address, hostname, home path, token or key. pnpm check:personal catches the common shapes,
and the rules in CLAUDE.md cover the rest.
Working in parallel
Andon is built by many agents at once, each in its own git worktree beside the main checkout. Two rules keep them apart:
- Postgres is per worktree.
pnpm dev,pnpm dev:demo,pnpm db:local, the server tests and Playwright use the worktree’s own.andon/pg. - Migrations are named by the current UTC time (
YYYYMMDDHHMMSS_<slug>.sql), so two branches never pick the same name. Schema changes has the rest.
Next
- Architecture: how the pieces fit, before your first real change.
- Testing: which suite needs which stack.
- CONTRIBUTING.md: how a change gets from your branch to
main.
