Environment Variables

This is the complete list of every supported environment variable, grouped by category. Start with the two rules that govern how variables are named and when they take effect, then jump to the category you need.

One canonical name per setting

A setting the browser needs (auth provider, cloud mode, feature flags) is inlined into the client bundle at build time as a VITE_* var. You do not set it twice. Set the canonical CHM_* name once and vite.config.ts derives the matching client VITE_*:

Precedence per var: explicit VITE_* → canonical CHM_* → legacy NEXT_PUBLIC_* → built-in default. The explicit VITE_* (and legacy NEXT_PUBLIC_*) forms still work as overrides.

A dual-surface setting must still be present at both build time (so vite inlines its VITE_*) and runtime (so the server reads it) — but it is the same single name in both places.

Client variable prefix by app

Browser-exposed variables are build-time inlined. The prefix depends on which app you run:

Tables below show the explicit VITE_* form for clarity, but you usually only set the canonical CHM_* name (above) and let the VITE_* derive. If you are migrating from v0.2, substitute NEXT_PUBLIC_ wherever you see VITE_. Server-side variables (CLICKHOUSE_*, CHM_*, LLM_*, CLERK_SECRET_KEY, etc.) are the same.

Authoritative example: apps/dashboard/.env.example.

Build-time vs runtime

There are two categories of environment variables:

All other vars (unless noted) are runtime — read from process.env when the Worker or Node process handles a request.

ClickHouse connection

Required. Set at least CLICKHOUSE_HOST.

CLICKHOUSE_HOST defines the host count. CLICKHOUSE_USER and CLICKHOUSE_PASSWORD may be either a single value (applied to all hosts) or one value per host position. CLICKHOUSE_NAME is optional. Position N maps to host index N.

See Multiple hosts and Custom name.

Query execution

Connection pool

Health alerting

The cron sweep (GET /api/cron/health-sweep, Cloudflare Cron Trigger every 5 minutes) runs health checks over all hosts and can post webhook alerts without a browser tab open.

# Alert Slack on warning-or-worse
CRON_SECRET=a-long-random-string
HEALTH_ALERT_ENABLED=true
HEALTH_ALERT_WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/XXXX
HEALTH_ALERT_MIN_SEVERITY=warning

Weekly health report

A second cron job (GET /api/cron/weekly-report) builds a proactive weekly HTML report per opted-in host — a 7-day narrative from the AI insights engine, adaptive statistical baselines, and the disk-capacity forecaster. Opt-in, never opt-out: reports are generated only for hosts listed in CHM_WEEKLY_REPORT_HOSTS.

# Opt host 0 and host 2 into the Monday 08:00 UTC weekly report
CRON_SECRET=a-long-random-string
CHM_WEEKLY_REPORT_HOSTS=0,2

Persisted regardless of delivery outcome; best-effort delivered to HEALTH_ALERT_WEBHOOK_URL (above) when configured. See Health — Weekly health report for the report contents and how to view a persisted report.

Prometheus metrics exporter

GET /api/v1/metrics serves system.metrics + system.asynchronous_metrics for every configured host (labeled host="<id>"), plus a chmonitor_alerts_firing gauge from the in-memory alert-dedup state, as Prometheus text exposition format. Cached ~30s; concurrent scrapes share one query batch.

# Scrape this instance from Prometheus
CHM_FEATURE_PROMETHEUS_ENABLED=true

# prometheus.yml
scrape_configs:
  - job_name: chmonitor
    scrape_interval: 30s
    metrics_path: /api/v1/metrics
    static_configs:
      - targets: ['dash.example.com']

OTel trace export

Exports chmonitor's OWN query traces — a dashboard-request span per request, with a nested clickhouse-query span per ClickHouse call carrying query_id/read_bytes/host attributes when available — to an external OTLP collector for correlation with the rest of your tracing stack. This is DISTINCT from the built-in OTel span viewer, which reads spans already stored in system.opentelemetry_span_log.

# Export to a local Jaeger instance (OTLP/HTTP receiver)
CHM_OTEL_EXPORTER_URL=http://jaeger:4318/v1/traces

Runs on Cloudflare Workers: the exporter uses OTLP/HTTP (not gRPC, which Workers cannot run), and the batch export is flushed inline before each response returns rather than deferred with waitUntil (Workers request middleware doesn't expose it here) — so export only adds latency when explicitly enabled.

Feature permissions

All features are public and enabled by default. Override only what needs different behavior.

Replace {ID} with an uppercase feature id: OVERVIEW, AGENT, INSIGHTS, HEALTH, QUERIES, TABLES, METRICS, DASHBOARD, SECURITY, LOGS, SETTINGS, BILLING, CLUSTER, OPERATIONS, ACTIONS, MCP, DOCS, ABOUT, PEERDB.

CHM_FEATURE_AGENT_ACCESS=authenticated
CHM_FEATURE_METRICS_ENABLED=false
CHM_DISABLED_FEATURES=settings,insights

See Feature permissions for config-file examples and precedence details.

Rate limiting

Per-IP (and, for the agent, per-signed-in-identity) request throttling on the SQL-executing API surfaces. All three share one implementation (lib/api/rate-limiter.ts, checkRateLimitDurable): an in-memory token bucket everywhere, upgraded to a fleet-wide Cloudflare Rate Limiting binding on Workers deploys (CHM_RATE_LIMIT_API / CHM_RATE_LIMIT_AGENT / CHM_RATE_LIMIT_MCP in wrangler.toml) so the limit holds across isolates, not just per-isolate. Requests over the limit get 429 with a Retry-After header. None of these need to be set for the defaults to apply.

Authentication

The active server-side auth provider is set by CHM_AUTH_PROVIDER. See Authentication for the full model.

Clerk (CHM_AUTH_PROVIDER=clerk)

Reverse proxy (CHM_AUTH_PROVIDER=proxy)

Trust a reverse proxy that already authenticated the user. Either mechanism below can authenticate a request.

Cloudflare Access JWT:

Trusted header (bare subject):

Trusted reverse proxy (CHM_AUTH_PROVIDER=trusted)

Use when an upstream proxy (oauth2-proxy, Authelia, Traefik ForwardAuth, nginx auth-url) forwards the user's full identity as HTTP headers. Extracts a complete principal — name, email, avatar, groups, custom claims.

Trust gate — configure exactly one:

Identity headers — all optional; defaults match common proxy conventions:

Access control:

See Trusted proxy for setup examples (oauth2-proxy + Dex + Traefik, nginx).

AI agent / LLM provider

The agent uses an OpenAI-compatible API. Set LLM_API_KEY to enable it. Keep all LLM keys server-side — never prefix them with VITE_.

Provider-specific keys

Provider-specific keys take priority over the generic LLM_API_KEY / LLM_API_BASE.

Agent behavior

See AI agent — configuration for full details.

Conversation store

Agent conversations default to browser localStorage. Enable server-side persistence with two steps:

AgentState backend:

Cloudflare D1 backend:

PostgreSQL backend:

See Conversation history — backends for setup and fallback behavior.

User connections (server storage)

Let signed-in users save personal ClickHouse hosts to the server. All four of these must be present together, or the server returns "User connections database storage is not enabled".

Plus a database backend: the CHM_CLOUD_D1 binding on Cloudflare, or DATABASE_URL / POSTGRES_URL on Docker / Kubernetes.

See User connections for the full setup.

AI insights store

The AI Insights panel on /overview persists its findings through a pluggable store. It is additive opt-in and defaults to ClickHouse; the D1, Postgres, and AgentState backends reuse the conversation-store env above.

postgres reuses DATABASE_URL; agentstate reuses AGENTSTATE_API_KEY (+ optional AGENTSTATE_BASE_URL).

See AI agent — AI Insights persistence for setup and fallback behavior. GET /api/v1/insights/backend reports the active backend.

PeerDB monitoring

Optional. Set PEERDB_API_URL to enable the PeerDB section (Mirrors and Peers) in the sidebar.

chmonitor proxies only a read-only allowlist of PeerDB endpoints; mutating operations (create/drop/pause, alert config) are rejected with 403.

# PeerDB UI behind NextAuth
PEERDB_API_URL=https://peerdb.example.com/api
PEERDB_PASSWORD=your-peerdb-ui-password

# Raw flow-api (no auth)
PEERDB_API_URL=http://localhost:8113

Analytics & branding

All client-side, all build-time. VITE_* for TanStack app; NEXT_PUBLIC_* for legacy Next.js.

Runtime & build

Build-time only

Injected at build time for the About page.

Query config source

Legacy / migration

See Migrate to v0.3 for the full rename list.

Related