For developers
Run Neo on your computer
The shortest safe setup guide for a developer working locally.
Quick start
cp .env.example .env
npm ci
npm run env:check
npm run db:migrate
npm run devNode.js 24, npm, and a local PostgreSQL database are required. Mock providers are the safe local default. Do not enable a live adapter merely to make local development work.
Environment-variable groups
| Group | Variables | Purpose |
|---|---|---|
| Origins/runtime | APP_ENV, public/app/API/docs URLs, host, port, process role | Environment, host separation, and process topology. |
| Database | DATABASE_URL, POSTGRES_DATABASE_URL | Runtime and explicit migration/test target. |
| Provider selection | Mock flags and provider names | Select a reviewed adapter or safe double. |
| Delivery/gates | Delivery modes, commerce, payout, refund, and beta flags | Control external writes and sandbox boundaries. |
| Certification | Environment and credential-version labels | Bind non-secret deployment identity to evidence. |
| Secrets | Provider tokens, webhook secrets, session secret, OTP pepper, AI key | Server-only secret store values; never public or committed. |
| Uploads | MinIO endpoint, keys, bucket, region, private directory | Private object storage. |
.env.example is the authoritative field-level reference. It contains placeholders only.
Validation behavior
Production rejects mock providers. Automated commerce writes require outbox delivery. Payout and refund gates fail closed when their provider or certification boundary is missing. Runtime database configuration accepts PostgreSQL only. Live tests are opt-in.
Environment errors are startup failures, not warnings. Fix the configuration rather than bypassing validation.
Safe commands
npm run db:start
npm run env:check
npm run typecheck
npm test
npm audit --omit=dev
npm run docs:checkProvider canaries and live AI smokes are intentionally not part of routine local setup. They require the correct target, credentials, cost/side-effect approval, and the relevant runbook.
README.md.env.examplesrc/env.tssrc/db.tstest/env.test.ts