# 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](https://andon-docs.pages.dev/contributing/local-development.md) 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](https://tauri.app/start/prerequisites/) |
| 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:

```sh
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:

   ```sh
   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:

   ```sh
   pnpm --filter @andon/shared --filter @andon/client build
   ```

3. Run the fast checks. None of them needs a database:

   ```sh
   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](https://andon-docs.pages.dev/contributing/local-development.md) 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](https://andon-docs.pages.dev/reference/env.md) 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](https://andon-docs.pages.dev/contributing/schema-changes.md) has the rest.

## Next

- [Architecture](https://andon-docs.pages.dev/contributing/architecture.md): how the pieces fit, before your first real change.
- [Testing](https://andon-docs.pages.dev/contributing/testing.md): which suite needs which stack.
- [CONTRIBUTING.md](https://github.com/psci-labs/andon/blob/main/CONTRIBUTING.md): how a change gets from your branch to `main`.
