Skip to main content
This page documents all environment variables used across Hazel Chat services. Variables are grouped by service and include descriptions, default values, and examples.

​
Quick Reference

Run bun run setup to automatically generate all .env files with proper values.

​
Required Services

ServiceEnv FilePurpose
Backendapps/backend/.envAPI server configuration
Webapps/web/.envFrontend configuration
Clusterapps/cluster/.envWorkflow service
Electric Proxyapps/electric-proxy/.envReal-time sync proxy
Databasepackages/db/.envDatabase migrations

​
Backend Variables

Configuration for the Effect-TS API server.

​
Database

​
DATABASE_URL
string
required
PostgreSQL connection string for the main application database.
DATABASE_URL=postgresql://user:password@localhost:5432/app
Production: Always use sslmode=verify-full for secure connections.

​
WorkOS Authentication

​
WORKOS_API_KEY
string
required
WorkOS API key for server-side authentication.
WORKOS_API_KEY=sk_test_abc123...  # Development
WORKOS_API_KEY=sk_live_xyz789...  # Production
Get from: WorkOS Dashboard → API Keys
​
WORKOS_CLIENT_ID
string
required
WorkOS client ID for your application.
WORKOS_CLIENT_ID=client_01ABCDEF123456
Get from: WorkOS Dashboard → Configuration → Client ID
​
WORKOS_REDIRECT_URI
string
required
OAuth callback URL for authentication flow.
WORKOS_REDIRECT_URI=http://localhost:3003/auth/callback
This URL must be added to Redirect URIs in your WorkOS dashboard.
​
WORKOS_COOKIE_DOMAIN
string
required
Domain for session cookies.
WORKOS_COOKIE_DOMAIN=localhost
​
WORKOS_WEBHOOK_SECRET
string
required
Secret for verifying WorkOS webhook signatures.
WORKOS_WEBHOOK_SECRET=whs_abc123...
Get from: WorkOS Dashboard → Webhooks → Webhook Secret

​
S3-Compatible Storage

​
S3_BUCKET
string
required
S3 bucket name for file uploads (works with Cloudflare R2, AWS S3, MinIO).
S3_BUCKET=hazel
​
S3_ENDPOINT
string
required
S3 API endpoint URL.
S3_ENDPOINT=http://localhost:9000
​
S3_ACCESS_KEY_ID
string
required
S3 access key ID.
S3_ACCESS_KEY_ID=your_access_key_id
Bun automatically reads S3_* variables. AWS_* variables work as fallback.
​
S3_SECRET_ACCESS_KEY
string
required
S3 secret access key.
S3_SECRET_ACCESS_KEY=your_secret_access_key

​
Service URLs

​
CLUSTER_URL
string
required
URL of the Effect Cluster service for background workflows.
CLUSTER_URL=http://localhost:3020
​
ELECTRIC_URL
string
required
URL of the Electric SQL proxy for real-time sync.
ELECTRIC_URL=http://localhost:5133
​
API_BASE_URL
string
required
Public URL of the backend API.
API_BASE_URL=http://localhost:3003
​
FRONTEND_URL
string
required
URL of the frontend application (for auth redirects).
FRONTEND_URL=http://localhost:3000

​
Redis

​
REDIS_URL
string
required
Redis connection URL for rate limiting and caching.
REDIS_URL=redis://localhost:6380

​
Integrations (Optional)

​
LINEAR_CLIENT_ID
string
Linear OAuth client ID for Linear integration.
LINEAR_CLIENT_ID=your_linear_client_id
​
LINEAR_CLIENT_SECRET
string
Linear OAuth client secret.
LINEAR_CLIENT_SECRET=your_linear_client_secret
​
LINEAR_REDIRECT_URI
string
Linear OAuth callback URL.
LINEAR_REDIRECT_URI=http://localhost:3003/integrations/linear/callback
​
DISCORD_CLIENT_ID
string
Discord bot client ID.
DISCORD_CLIENT_ID=your_discord_client_id
​
DISCORD_CLIENT_SECRET
string
Discord bot client secret.
DISCORD_CLIENT_SECRET=your_discord_client_secret
​
DISCORD_BOT_TOKEN
string
Discord bot token.
DISCORD_BOT_TOKEN=your_discord_bot_token
​
DISCORD_GATEWAY_ENABLED
boolean
default:"false"
Enable Discord gateway connection.
DISCORD_GATEWAY_ENABLED=true
​
DISCORD_GATEWAY_INTENTS
number
default:"34305"
Discord gateway intents bitmask.
DISCORD_GATEWAY_INTENTS=34305

​
Observability (Optional)

​
OTLP_ENDPOINT
string
OpenTelemetry Protocol endpoint for traces.
OTLP_ENDPOINT=http://localhost:4318/v1/traces
Supported backends:
  • Honeycomb
  • Datadog
  • Grafana Tempo
  • Jaeger

​
Web (Frontend) Variables

Configuration for the React frontend application.
All frontend variables are prefixed with VITE_ to be included in the build.

​
Backend URLs

​
VITE_BACKEND_URL
string
required
URL of the backend API server.
VITE_BACKEND_URL=http://localhost:3003
​
VITE_CLUSTER_URL
string
required
URL of the cluster service.
VITE_CLUSTER_URL=http://localhost:3020

​
WorkOS

​
VITE_WORKOS_CLIENT_ID
string
required
WorkOS client ID (same as backend).
VITE_WORKOS_CLIENT_ID=client_01ABCDEF123456
​
VITE_WORKOS_REDIRECT_URI
string
required
Frontend OAuth callback URL.
VITE_WORKOS_REDIRECT_URI=http://localhost:5173/auth/callback
This is different from the backend redirect URI. The frontend callback receives the code and exchanges it via the backend.

​
Electric SQL

​
VITE_ELECTRIC_URL
string
required
Electric SQL proxy URL for real-time sync.
VITE_ELECTRIC_URL=http://localhost:8787/v1/shape
The Electric proxy adds authentication and caching. Using the proxy is recommended over direct Electric connection.

​
CDN

​
VITE_R2_PUBLIC_URL
string
required
Public CDN URL for uploaded files.
VITE_R2_PUBLIC_URL=http://localhost:9000/hazel

​
Cluster Variables

Configuration for the Effect Cluster workflow service.

​
Database

​
DATABASE_URL
string
required
PostgreSQL connection string (same as backend).
DATABASE_URL=postgresql://user:password@localhost:5432/app
​
EFFECT_DATABASE_URL
string
required
Dedicated database for Effect Cluster persistence.
EFFECT_DATABASE_URL=postgresql://user:password@localhost:5432/cluster
The cluster service uses a separate database for workflow state isolation.

​
Electric Proxy Variables

Configuration for the Cloudflare Worker proxy.
​
PORT
number
default:"8184"
Server port for local development.
PORT=8184
​
DATABASE_URL
string
required
PostgreSQL connection string.
DATABASE_URL=postgresql://user:password@localhost:5432/app
​
IS_DEV
boolean
default:"false"
Development mode flag.
IS_DEV=true
​
ELECTRIC_URL
string
required
Electric SQL service URL.
ELECTRIC_URL=http://localhost:3333
​
ELECTRIC_SOURCE_ID
string
Electric Cloud source ID (only for Electric Cloud).
ELECTRIC_SOURCE_ID=your_source_id
​
ELECTRIC_SOURCE_SECRET
string
Electric Cloud source secret.
ELECTRIC_SOURCE_SECRET=your_source_secret
​
WORKOS_API_KEY
string
required
WorkOS API key for authentication.
WORKOS_API_KEY=sk_test_...
​
WORKOS_CLIENT_ID
string
required
WorkOS client ID.
WORKOS_CLIENT_ID=client_...
​
ALLOWED_ORIGIN
string
required
CORS allowed origin.
ALLOWED_ORIGIN=http://localhost:3000
​
OTLP_ENDPOINT
string
OpenTelemetry endpoint for observability.
OTLP_ENDPOINT=http://localhost:4318/v1/traces

​
Database Package Variables

Configuration for Drizzle ORM migrations.
​
DATABASE_URL
string
required
PostgreSQL connection string for migrations.
DATABASE_URL=postgresql://user:password@localhost:5432/app

​
Environment File Templates

​
Backend Template

apps/backend/.env.example
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/app

# Cluster
CLUSTER_URL=http://localhost:3020

# WorkOS
WORKOS_API_KEY=sk_test_your_api_key
WORKOS_CLIENT_ID=client_your_client_id
WORKOS_REDIRECT_URI=http://localhost:3003/auth/callback
WORKOS_COOKIE_DOMAIN=localhost
WORKOS_WEBHOOK_SECRET=your_webhook_secret

# S3 Storage
S3_BUCKET=hazel
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin

# Electric
ELECTRIC_URL=http://localhost:5133

# Redis
REDIS_URL=redis://localhost:6380

# URLs
API_BASE_URL=http://localhost:3003
FRONTEND_URL=http://localhost:3000

​
Web Template

apps/web/.env.example
# Backend
VITE_BACKEND_URL=http://localhost:3003
VITE_CLUSTER_URL=http://localhost:3020

# WorkOS
VITE_WORKOS_CLIENT_ID=client_your_client_id
VITE_WORKOS_REDIRECT_URI=http://localhost:5173/auth/callback

# Electric
VITE_ELECTRIC_URL=http://localhost:8787/v1/shape

# CDN
VITE_R2_PUBLIC_URL=http://localhost:9000/hazel

​
Cluster Template

apps/cluster/.env.example
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/app
EFFECT_DATABASE_URL=postgresql://user:password@localhost:5432/cluster

​
Setup Wizard

The setup wizard automatically generates all .env files: 
bun run setup
This interactive CLI will:
  1. Start Docker services
  2. Validate your environment
  3. Configure WorkOS authentication
  4. Generate secrets
  5. Create all .env files
  6. Initialize the database
The setup wizard is the recommended way to configure environment variables for development.

​
Security Best Practices

Never commit .env files to git. They are included in .gitignore by default.

​
Secret Management

1

Use different keys per environment

Development and production should have completely different secrets.
2

Rotate secrets regularly

Rotate API keys, database passwords, and other secrets every 90 days.
3

Use secret management services

For production, consider:
  • AWS Secrets Manager
  • HashiCorp Vault
  • Doppler
  • 1Password Secrets Automation
4

Restrict access

Limit who can access production secrets.

​
Next Steps

Getting Started

Set up your development environment

Deployment

Deploy to production

WorkOS Configuration

Configure authentication

Database Setup

Set up PostgreSQL

Build docs developers (and LLMs) love

Get started for freeTalk to us