Configuration
Environment Variables
Complete reference for all GridWork HQ environment variables.
GridWork HQ uses two environment files: .env.local in the dashboard package and .env in the pipeline server. The setup wizard generates both files.
Every feature checks whether its env vars are present. Missing keys show "Not configured" in the UI — the app never crashes on missing optional variables.
| Variable | Required | Description |
|---|
HQ_URL | Yes | Your deployed HQ URL (no trailing slash). Example: https://hq.yourdomain.com |
NEXTAUTH_URL | Local only | Set to http://localhost:3000 for local dev. Do NOT set on Vercel. |
NODE_ENV | No | production or development. Defaults to production. |
| Variable | Required | Description |
|---|
GITHUB_ID | Yes | GitHub OAuth App Client ID |
GITHUB_SECRET | Yes | GitHub OAuth App Client Secret. Security-sensitive. |
NEXTAUTH_SECRET | Yes | JWT signing key. Generate with openssl rand -base64 32. Rotate periodically. |
ALLOWED_GITHUB_ID | Yes | Your numeric GitHub user ID. Restricts dashboard login to this account. Find yours at https://api.github.com/users/YOUR_USERNAME. |
| Variable | Required | Description |
|---|
GITHUB_TOKEN | Yes | Personal access token with repo and read:org scopes |
GITHUB_ORG | Yes | Your GitHub org or username |
TRACKED_REPOS | No | Comma-separated list of repos to display on the dashboard |
| Variable | Required | Description |
|---|
NOTION_API_KEY | Yes | Notion integration secret from notion.so/my-integrations |
NOTION_LEADS_DB | Yes | Leads database ID (32-character hex string from the database URL) |
NOTION_CLIENTS_DB | Yes | Clients database ID |
| Variable | Required | Description |
|---|
STRIPE_SECRET_KEY | No | Stripe secret key. Use test mode keys (sk_test_...) for development. |
STRIPE_WEBHOOK_SECRET | No | Stripe webhook signing secret for invoice event processing |
| Variable | Required | Description |
|---|
ANTHROPIC_API_KEY | Yes | Anthropic API key for the AI chat feature and server-side API calls. Security-sensitive — never commit. |
| Variable | Required | Description |
|---|
PERPLEXITY_API_KEY | No | Perplexity API key for research in prospect and audit pipelines |
| Variable | Required | Description |
|---|
PIPELINE_SERVER_TOKEN | Yes | Shared secret between dashboard and pipeline server. Generate with openssl rand -hex 32. Must match the pipeline server. |
PIPELINE_SERVER_URL | Yes | Full URL to your pipeline server (e.g., http://localhost:8750 or https://your-machine.tail12345.ts.net) |
PIPELINE_SERVER_PORT | Yes | Port the pipeline server listens on. Default: 8750 |
DUCTOR_WEBHOOK_TOKEN | Yes | Webhook token for HQ-to-pipeline-server communication. Must match the pipeline server. |
| Variable | Required | Description |
|---|
VERCEL_API_KEY | No | Vercel personal access token for deployment status checks |
VERCEL_TEAM_ID | No | Vercel team ID. Leave blank for personal accounts. |
| Variable | Required | Description |
|---|
GOOGLE_SERVICE_ACCOUNT_JSON | No | Google Cloud service account JSON as a single-line string |
GA4_PROPERTY_ID | No | GA4 property ID (e.g., 123456789) |
GSC_SITE_URL | No | Google Search Console site URL (e.g., https://www.yourdomain.com) |
| Variable | Required | Description |
|---|
UPTIMEROBOT_API_KEY | No | UptimeRobot API key for uptime tracking |
UPTIMEROBOT_MONITOR_ID | No | UptimeRobot monitor ID |
| Variable | Required | Description |
|---|
DATABASE_URL | No | SQLite file path or Turso URL. Default: file:./data/gridwork-hq.db. For Vercel, use Turso (e.g., libsql://your-db.turso.io). |
DATABASE_AUTH_TOKEN | No | Turso auth token. Only needed when using Turso. |
| Variable | Required | Description |
|---|
NEXT_PUBLIC_SYSTEM_USERS | No | Comma-separated GitHub usernames labeled as "system" in activity feeds |
The pipeline server has its own .env file with these key variables:
| Variable | Required | Description |
|---|
PIPELINE_SERVER_TOKEN | Yes | Must match the dashboard's PIPELINE_SERVER_TOKEN |
HQ_URL | Yes | URL of the dashboard (e.g., http://localhost:3000 or your Vercel URL) |
DUCTOR_WEBHOOK_TOKEN | Yes | Must match the dashboard's DUCTOR_WEBHOOK_TOKEN |
ANTHROPIC_API_KEY | Yes | API key for spawning Claude Code processes |
KNOWLEDGE_DIR | Yes | Absolute path to your knowledge vault (e.g., /Users/you/agency-workspace/knowledge) |
SCRIPTS_DIR | No | Path to shell scripts directory (e.g., /Users/you/agency-workspace/.scripts) |
TELEGRAM_BOT_TOKEN | No | Telegram bot token for notifications |
TELEGRAM_CHAT_ID | No | Your Telegram chat ID for receiving notifications |
MAX_PARALLEL_PIPELINES | No | Maximum concurrent pipeline jobs. Default: 3 |
- Never commit
.env.local or .env files to git — both are in .gitignore
- Rotate
NEXTAUTH_SECRET periodically: openssl rand -base64 32
- Rotate
PIPELINE_SERVER_TOKEN periodically: openssl rand -hex 32
- Use Stripe test mode keys (
sk_test_...) for development
- The
ALLOWED_GITHUB_ID restricts who can log in to your dashboard