Local development setup

This page gets a working ErmisAI dev server on your machine and explains the version pins and environment traps that break a first run. Paths are relative to the app repository root (the directory is named hermesai; the package is ermisai).

Prerequisites

pnpm is the only supported package manager. Corepack pins it to 11.15.1 from the packageManager field regardless of what you have installed globally.

mise.toml contains exactly one entry:

[tools]
pnpm = "latest"

It does not pin Node, and there is no .nvmrc or .tool-versions in the repo. Your Node version is your responsibility. CI runs Node 24 (.github/workflows/ci.yml). Node 20 will refuse to install.

Install

pnpm install

Environment file

Copy the committed example and fill it in:

cp .env.example .env

.gitignore ignores .env* and un-ignores only .env.example, so nothing you write into .env or .env.local can be committed by accident.

The minimum to boot

You do not need Polar, Resend, Upstash, Sentry or an AI provider to get the dev server up. The genuine minimum is Clerk plus one of the two storage choices below.

README.md:34-37 also asks you to set the four Clerk URL variables in both their server and NEXT_PUBLIC_ forms: CLERK_SIGN_IN_URL=/sign-in, CLERK_SIGN_UP_URL=/sign-up, and both fallback redirect URLs to /app.

Running without Postgres

ERMIS_FORCE_INMEMORY_STORE=true

This routes the shared runtime state store (platform_state / platform_state_hash) to an in-memory implementation, so the app boots with no database at all. Everything you create is lost when the dev server restarts, and nothing that pnpm db:seed-bootstrap would have written — the billing plan rows, the synced source catalog rows — exists.

Production has no state fallback at all: if platform_state is unreachable or unmigrated, every authenticated surface fails. That is deliberate. See Database schema and runtime state.

Database setup

Two URLs, two resolution orders

The application runtime and drizzle-kit deliberately read different variables in a different order.

MIGRATIONS_DATABASE_URL exists because DDL through a transaction-mode pooler is unreliable. Point it at the direct or session endpoint. On CapyDB the same host serves both: :6432 is the pooled endpoint for the app runtime, :5432 is the direct endpoint for DDL only (.env.example:19-25).

Migrate and seed

pnpm db:migrate

pnpm db:seed-bootstrap

Bootstrap seed completed.
billing_plans=<n>
source_catalog_entries=<n>
source_catalog_dataset_versions=<n>
catalog_entries=<n>
catalog_version=<v>

pnpm db:check

node --env-file=.env --import tsx scripts/db/seed-bootstrap.ts

Never use npx for drizzle-kit

Use pnpm db:migrate or pnpm exec drizzle-kit. The production migration gate spells out why in its own header: it spawns pnpm exec and "NOT npx — npx re-resolves and trips the version gate" (scripts/deploy/prod-migrate.ts:14-15).

The repo is on drizzle-kit and drizzle-orm 1.0.0-rc.4, whose layout is one directory per migration (drizzle/<timestamp>_<name>/migration.sql + snapshot.json) with intentionally no drizzle/meta/_journal.json. If you are about to change schema.ts, read Migrations and schema changes first.

First run

pnpm dev

Open http://localhost:3000.

To confirm the backend is actually wired up, hit the readiness probe — it is one of only two API routes that require no authentication:

curl -s http://localhost:3000/api/health | jq

It returns HTTP 200 when checks.database.status === 'ok' and 503 otherwise (src/app/api/health/route.ts:144,161). Redis being absent reports "status": "not_configured" and never fails readiness. The useful field on day one is checks.database.migrated: when the platform_state probe fails you get migrated: false and

platform_state unreachable (run db:migrate before serving traffic): <error>

The config block lists ten launch-critical environment keys and whether each is present. It is informational locally — config.ready: false does not change the HTTP status. See Deploying to production.

Version pins that must not change

Bleeding-edge dist-tags (canary, next, rc, beta, experimental) are deliberate policy across the dependency tree. Never downgrade one to fix a local problem.

The cost of that policy is drift: an option that a next canary drops becomes a type error on your machine with no change from you. This is real and currently visible — pnpm typecheck fails on next.config.ts:435:

next.config.ts(435,5): error TS2353: Object literal may only specify known properties,
and 'imgOptSkipMetadata' does not exist in type 'ExperimentalConfig'.

When pnpm typecheck goes red in a file you never touched, check next.config.ts against the installed canary before assuming your branch is at fault.

Day-one surprises

• pnpm lint prints nothing. It is oxlint -f github src/ > lint.md 2>&1 (package.json:32) — both streams are redirected into lint.md at the repo root. Read that file, or the exit code. Use pnpm lint:fix for terminal output.
• pnpm build performs no type checking at all. typescript.ignoreBuildErrors: true is set deliberately (next.config.ts:113-118) because the build-time check needs the programmatic TS API that native TS 7.0 does not expose. Type safety comes solely from pnpm typecheck.
• pnpm build hard-sets NODE_ENV=production (package.json:11-12). A NODE_ENV=development exported in your shell otherwise leaks into next build and breaks prerendering.
• pnpm lint and pnpm format only cover src/. scripts/, tests/ and drizzle/ are outside their scope.
• pnpm test is noisy on a green run. Suites deliberately exercise failure paths, so lines like [news-pipeline] synthesis attempt failed (…) and [billing-status] unrecognized Polar subscription status … are expected output, not failures.
• AGENTS.md rewrites itself. next dev regenerates it (node_modules/next/dist/server/lib/generate-agent-files.js). Removing it from a diff just recreates the uncommitted change.
• Formatting is oxfmt, linting is oxlint. There is no ESLint config and no Prettier config in the repo. .oxfmtrc.jsonc sets no semicolons, single quotes and printWidth 100; .oxlintrc.json sets "typeAware": true, so even a plain pnpm lint runs type-aware rules.

Commands you will use most

Tests live in tests/*.vitest.ts and are not colocated with source. They run in plain node with server-only aliased to an inert stub and part of the environment neutralised by tests/setup.env.ts. The full script inventory and the structural gates that fail CI are on Scripts, quality gates and CI.