Environment Variables

Self-hosters need three vars. Everything else is optional and listed here.

CLICKHOUSE_HOST=http://localhost:8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=

Copy apps/dashboard/.env.example for a short template. Polar license checkout belongs on landing / apps/cloud-hooks, not the standalone monitor.

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.

Operators set CHM_* (and CLICKHOUSE_* / third-party secrets). Do not also set VITE_*. The build derives client values. Legacy NEXT_PUBLIC_* still works as a fallback — see Migrate to v0.3.

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 for a working dashboard: host, user, password. Name is optional.

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 four 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 / CHM_RATE_LIMIT_BROWSER_CONN 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.

ClickHouse state backend (self-hosted):

Persists dashboards and per-user connections in your own ClickHouse instead of Cloudflare D1 or Postgres. Opt-in; tables are created lazily (CREATE TABLE IF NOT EXISTS, ReplacingMergeTree). Resolution order per store: D1 binding → ClickHouse state env → Postgres env → local/memory.

See Self-hosted state backends for setup.

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

Set the canonical CHM_* names. Client VITE_* is derived at build time.

Build-time branding overrides (optional; do not set unless you custom-build): VITE_TITLE_SHORT, VITE_LOGO, VITE_AUTOCOMPLETE_LIMIT, VITE_MEASUREMENT_ID.

CLI client

Env vars for the standalone chm / chmonitor CLI (crate chmonitor). These are read by the binary and scripts/install.sh, not by the dashboard server. Flags override env; env overrides ./chm.toml / ~/.config/chm/config.toml. Default API base is https://dash.chmonitor.dev.

chm auth login discovers how to authenticate by probing public GET /api/v1/auth/cli (method: none | api_key | device) — there is no auth_mode in config. See API keys — device login.

Installer (scripts/install.sh)

Server-side device login gates (CHM_DEVICE_LOGIN, CHM_API_KEY_SECRET, …) live under Authentication.

Product telemetry

Anonymous product telemetry is on by default. See Product telemetry.

Polar licenses (landing / cloud-hooks)

Self-host license checkout is not configured on the dashboard example. Set Polar product ids and secrets on apps/cloud-hooks (and the hosted .env.production catalog). See apps/cloud-hooks/.env.example. Operators who already bought a license set CHM_LICENSE_KEY on the dashboard process (see Product telemetry above) — not on cloud-hooks.

Ops notifications worker (cloud-hooks)

apps/cloud-hooks is the Cloudflare Worker for Polar license checkout, Clerk lifecycle hooks, health-probe digests, and exception/issue-watch notifications. Bindings (CHM_CLOUD_D1, CHM_TELEMETRY_DB, CHM_HOOKS_KV) are declared in apps/cloud-hooks/wrangler.toml, not here. See apps/cloud-hooks/.env.example.

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