Reference
Configuration
Environment variables read by the web app and worker.
Environment variables
| HEADWIND_PASSWORD | Shared team password. Required to sign in. |
|---|---|
| HEADWIND_DB | Path to the SQLite file. Default ./data/headwind.db. |
| LITELLM_BASE_URL, LiteLLM_API_KEY, HEADWIND_MODEL | OpenAI-compatible model gateway and model name. |
| CRUSTDATA_API_KEY | Crustdata key for company and listing checks. |
| CFO_TOKEN_FILE | Path to the cfo.ai OAuth token file. |
| NEATLOGS_API_KEY, NEATLOGS_ENDPOINT | Run traces. |
| HEADWIND_UPSTREAM | Vercel only. The app server's URL. When set, this copy serves the public pages and passes /app, /import, /login and /api to that server. |
| HEADWIND_PROXY_KEY | Same secret on Vercel and the app server. The app server trusts the visitor's host and address only from requests carrying it. |
| HEADWIND_ASSET_PREFIX | App server only, set to /_hw for the Vercel setup, so its page files load through the Vercel address. |
Run locally
npm install
cp .env.example .env.local
npx tsx scripts/seed-sample.ts
npm run dev
npm run workerDeploy
The deploy folder runs the web app, worker, weekly timer and Caddy on one Ubuntu 24.04 server. Keys go in /etc/headwind/env. For one public address, deploy the same repo to Vercel with HEADWIND_UPSTREAM and HEADWIND_PROXY_KEY set: Vercel serves the landing page and docs, and passes sign-in, the app and the API to the server, where the data and worker stay.