Quickstart

Local setup, environment groups, and the main commands used to work on HermesAI.

Stack baseline

HermesAI currently runs on:

Next.js 16 App Router
React 19
TypeScript
Tailwind CSS v4
Clerk for authentication
Postgres + Drizzle ORM for durable relational state
Upstash Redis for mutable runtime state
Polar for billing
Vercel AI SDK / AI Gateway for model routing

Source-of-truth

The root README.md remains the exhaustive environment inventory. This page mirrors it but trims to the practical groupings — when they disagree, the README wins.

Prerequisites

Node.js 20+

The runtime version pinned by Next.js 16.

pnpm 10+

Package manager. Lockfile is `pnpm-lock.yaml`.

Postgres

Local instance or a Supabase Postgres URL for the application runtime.

Upstash Redis

REST URL + token for runtime mutable state.

Clerk

Application credentials, sign-in/sign-up URLs, and the webhook signing secret.

Polar

Access token plus the webhook secret for billing event sync.

Local setup

Install dependencies

pnpm install

Wire up `.env.local`

Copy .env.example and fill in the groups described below. The minimum viable set is auth + database + Redis + AI Gateway.

Run the dev server

pnpm dev

The default local URL is http://localhost:3000.

Verify the catalog and database

pnpm db:check
pnpm catalog:validate

Environment groups

The full surface is long. The easiest way to reason about it is by capability area.

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
CLERK_SECRET_KEY
CLERK_WEBHOOK_SIGNING_SECRET
Clerk sign-in / sign-up URLs and fallback redirect URLs

SUPABASE_DATABASE_URL or DATABASE_URL
SUPABASE_URL or NEXT_PUBLIC_SUPABASE_URL
SUPABASE_SERVICE_ROLE_KEY
SUPABASE_STORAGE_PUBLIC_BUCKET
SUPABASE_STORAGE_ARCHIVE_BUCKET
OBJECT_STORAGE_PROVIDER
BLOB_READ_WRITE_TOKEN

UPSTASH_REDIS_REST_URL
UPSTASH_REDIS_REST_TOKEN
REDIS_URL or KV_URL when resumable chat streams are enabled

POLAR_ACCESS_TOKEN
POLAR_WEBHOOK_SECRET
POLAR_SERVER
Plan product IDs for Free, Plus, Pro, Business, and Enterprise

AI_GATEWAY_API_KEY
HERMES_AI_PROVIDER_MODE
Azure variables when running in direct Azure mode
Model override and prompt-version variables when testing provider behavior

Verified commands

pnpm dev
pnpm build
pnpm start

pnpm typecheck
pnpm test
pnpm lint

pnpm db:generate
pnpm db:migrate
pnpm db:check
pnpm db:studio

pnpm catalog:build
pnpm catalog:validate
pnpm catalog:coverage
pnpm catalog:audit

Project layout

Things to keep straight

Architectural reality

The tenant product and the platform admin are intentionally separate.
The current architecture is not a BullMQ-style durable worker system.
The source catalog lives in checked-in JSON and is only synced into Postgres through the explicit admin sync route.
Public product claims should stay aligned to the surfaces already implemented in src/app.