Settings Reference
Brand configuration, setup wizard phases, and in-app settings for GridWork HQ.
Settings Reference
Beyond environment variables, GridWork HQ is configured through the brand configuration file and the setup wizard.
Brand Configuration (config/brand.json)
The setup wizard generates gridwork-hq/config/brand.json with your agency's visual identity. This file is committed to git and controls the dashboard appearance.
Key fields:
| Field | Description | Example |
|---|---|---|
name | Your agency name | "Acme Digital" |
domain | Your agency domain | "acmedigital.com" |
sidebarTitle | Text shown at the top of the sidebar | "Acme HQ" |
primaryColor | Primary accent color (hex) | "#3b82f6" |
backgroundColor | Main background color (hex) | "#0a0a0a" |
fonts.heading | Heading font family | "Satoshi" |
fonts.body | Body font family | "Inter" |
To modify after initial setup, edit config/brand.json directly and restart the dashboard.
Setup Wizard Phases
The setup wizard (node setup-wizard.mjs) runs 5 phases:
Phase 1: Agency Identity
- Agency name
- Agency domain
- Contact email
- Timezone
Phase 2: Theme and Branding
- Primary color
- Background color
- Heading font
- Body font
- Sidebar title
Phase 3: Integrations
- Anthropic API key
- GitHub OAuth credentials
- GitHub personal access token
- Notion API key and database IDs
- Stripe API key (optional)
- Vercel API key (optional)
- Perplexity API key (optional)
- Google service account (optional)
- Telegram bot token (optional)
Phase 4: Infrastructure
- Deployment target (local, vps, vercel)
- Knowledge vault path
- Scripts directory path
- Pipeline server port (default: 8750)
- Tailscale configuration (optional)
Phase 5: AI Configuration
- Telegram bot setup
- Default model tier
- Cron job preferences
Press Enter to accept defaults shown in brackets. You can skip optional keys and add them later by editing the .env files directly.
Knowledge Vault Placeholders
All knowledge vault templates use {{AGENCY_*}} placeholders that the setup wizard substitutes with your real values:
| Placeholder | Replaced With |
|---|---|
{{AGENCY_NAME}} | Your agency name |
{{AGENCY_EMAIL}} | Your contact email |
{{AGENCY_PHONE}} | Your phone number |
{{AGENCY_URL}} | Your agency website URL |
{{AGENCY_OWNER}} | Your name |
{{AGENCY_GITHUB_ORG}} | Your GitHub org/username |
Pipeline Server Settings
Max Parallel Pipelines
Set via the MAX_PARALLEL_PIPELINES environment variable. Default: 3. Controls how many Claude Code processes can run simultaneously. Increase if you have ample RAM (each process uses approximately 500 MB - 1 GB).
SSE Rate Limiting
The pipeline server rate-limits SSE connections to 20 per minute per IP address. This is not configurable — it prevents connection flooding from misbehaving clients.
Quiet Hours
Each cron job can define quiet hours using quiet_start and quiet_end (UTC hours) in cron-config.json. During quiet hours, scheduled executions are silently skipped.
Cron Configuration
See the dedicated Cron Jobs Configuration page for all 12 cron jobs and their settings.
Database Settings
GridWork HQ uses SQLite via Drizzle ORM by default. The database is auto-created on first run at ./data/gridwork-hq.db.
For Vercel deployments, use Turso (a hosted SQLite-compatible database). Set DATABASE_URL to your Turso URL and DATABASE_AUTH_TOKEN to your Turso auth token.
After schema changes (when pulling updates), run:
cd gridwork-hq
bun run migrate