Skip to content
AndonDocs
GitHub
Change Andon

Set up from zero

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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:

shell
brew install node@22 pnpm git colima docker tmux ffmpeg gh rustup
colima start

On Debian or Ubuntu, sudo apt-get install -y tmux ffmpeg git, Node 22 from your usual source, and Docker Engine.

Clone and build

  1. Clone the repository and install the dependencies:

    shell
    git clone https://github.com/psci-labs/andon && cd andon
    pnpm install
  2. 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
  3. Run the fast checks. None of them needs a database:

    shell
    pnpm typecheck
    pnpm lint
    pnpm check:personal
    pnpm check:docs
    pnpm exec vitest run --project board --project agent --project @andon/shared
  4. Start the app with pnpm dev and open the address it prints. The first run seeds a demo org and writes its logins to .env.local. Local development says what else pnpm dev can 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