Local development
Run OpenDash from source on your machine, seed sample companies to ask about, and the commands you'll use every day.
Prerequisites
| Tool | Version | Notes |
|---|---|---|
| Node.js | 24 LTS (.nvmrc) | nvm use |
| pnpm | pinned in packageManager | Run corepack enable once |
| Docker | Compose v2 | Postgres 17 with pgvector on 127.0.0.1:5444 (5432 is often taken) |
| git | any recent | Commits are signed off (git commit -s) |
First run
corepack enable && pnpm install
cp .env.example .env.local # set BETTER_AUTH_SECRET and OPENDASH_KEK: openssl rand -base64 32 for each
pnpm dxpnpm dx checks your setup, starts Postgres, creates the database roles, runs migrations (which also install the job queues), and starts the web app and the worker. Every step is safe to re-run.
Open localhost:3000/sign-up, sign up, and open the link. Without an email provider, development prints each link in the web server's log. Then create an organization.
The analyst needs a model: put a key in .env.local (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY or AI_GATEWAY_API_KEY), or add one for the workspace under Settings → AI.
Sample data
| Command | What you get |
|---|---|
pnpm demo:seed | Acme, a SaaS company (the DashBench dataset), as database opendash_demo with read-only user opendash_demo_reader |
pnpm demo:seed --clickhouse / --mysql | The same company in ClickHouse or MySQL (start them with pnpm clickhouse:up / pnpm mysql:up) |
pnpm demo:seed --commerce | Lumen, a home-lighting brand: about 125,000 orders, returns, campaigns, stock and support tickets in four currencies |
| Data → Connect source → Use the playground | ClickHouse's public playground: house prices, GitHub events, taxi trips and more |
The seed command prints the connection details. Connect them under Data → Connect source like any other database.
Everyday commands
| Command | What it does |
|---|---|
pnpm dev | Web app and worker in watch mode |
pnpm lint / pnpm lint:fix | Biome lint and format |
pnpm typecheck | Strict TypeScript |
pnpm test | Vitest unit and integration tests (needs pnpm db:up) |
pnpm build | Every package and the web app |
pnpm db:up / pnpm db:down | Start or stop the development databases |
pnpm db:migrate | Apply migrations and install the job queues |
pnpm dev:doctor | Check Node, pnpm, Docker, ports and settings, with a fix hint for each |
pnpm ask "question" | Ask the analyst from the terminal and watch the run: thinking, SQL, results, the gate, the answer |
pnpm golden | 21 questions about the sample company, graded against answers computed from the data |
pnpm evals | The full DashBench run |
pnpm slack:manifest / pnpm slack:tunnel | The Slack app manifest for your address, or a local tunnel |
Conventions
- TypeScript strict, ESM, Node 24. Files in kebab-case, React components in PascalCase. Biome only.
- Only
withTenant(ctx, fn)touches tenant data. Importing the raw database handle is lint-banned. Never hold a transaction open across a model call or a warehouse query. - New tables use the
(org_id, id)primary key, composite foreign keys and row-level security policies; the tenancy suite checks it. - Migrations are forward-only and must work with the previous version running.
- Secrets are never logged, never put in prompts, and never returned to the client.
Troubleshooting
| Symptom | Fix |
|---|---|
| Port 3000 in use | PORT=3010 pnpm dev |
| Streams never update | Use a direct connection for DATABASE_DIRECT_URL |
| "No worker has picked up the check yet" | Run pnpm dev (web and worker), not only the web app |
relation "pgboss.job" does not exist | pnpm db:migrate |
| A workspace is stuck without its data key | pnpm auth:repair |