chmonitor Dashboard

chmonitor is an operational advisor for self-hosted ClickHouse — not just a metrics viewer. It reads system.* and recommends projections, skip indexes, partition keys, PREWHERE rewrites, and materialized views (it recommends, and never auto-applies DDL), on top of the real-time query/cluster/replication monitoring you'd expect. Managed-ClickHouse AI tools stay locked to their own Cloud; chmonitor works the same way on Docker, Kubernetes, bare metal, or ClickHouse Cloud.

A modern dashboard (TanStack Start, as of v0.3) that provides real-time insights into ClickHouse clusters through system tables. Every page is pre-rendered at build time with client-side data fetching for optimal performance and CDN caching.

Upgrading from v0.2? v0.3 rebuilds the app on TanStack Start. ClickHouse connection vars are unchanged; browser vars move from NEXT_PUBLIC_* to VITE_* (old names still work as a fallback). See Upgrading to v0.3 below or the full Migrate to v0.3 guide.

Live: dash.chmonitor.dev | chmonitor.dev | Screenshots

Features:

• Query Monitoring: Running queries, query history, resources (memory, parts read, file_open), expensive queries, slow queries, failed queries, query profiler
• Cluster Overview: Memory/CPU usage, distributed queue, global settings, MergeTree settings, metrics, asynchronous metrics
• Data Explorer: Interactive database tree browser with fast tab switching and column-level details, projections, dictionaries
• Table Analytics: Size, row count, compression, part sizes with column-level granularity, detached parts, readonly tables, view refreshes
• Visualization: 30+ metric charts for queries, resources, merges, performance, and system health
• Merge & Replication: Merge operations, merge performance, replication queue, replicas
• Security & Access: Users, roles, security settings
• Developer Tools: Zookeeper explorer, query EXPLAIN, query kill, distributed DDL queue, mutations
• Multi-Host Support: Monitor multiple ClickHouse instances from a single dashboard
• AI Advisor: Query optimization advisor, materialized-view/projection designer, capacity forecast + TTL advisor, and EXPLAIN-based query cost estimator — all recommend-only, never auto-applies DDL
• AI Agent: Built-in AI chat for natural language queries against your ClickHouse cluster
• MCP Server: Model Context Protocol endpoint for AI tool integration (Claude, Cursor, etc.)
• Rust CLI: Standalone terminal and TUI monitoring tool

Quick start

One container, pointed at any reachable ClickHouse (OSS, Altinity, or ClickHouse Cloud):

docker run -d --name chmonitor -p 3000:3000 \
  -e CLICKHOUSE_HOST=https://clickhouse.example.com:8443 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=change-me \
  ghcr.io/chmonitor/chmonitor:latest

Open http://localhost:3000. Pin a release tag instead of latest for production.

Just want to look first? The live demo is at dash.chmonitor.dev — no setup required. Other targets (Cloudflare Workers, one-click Railway/Render/Fly, Kubernetes) are under Deployment.

Deployment

chmonitor is self-hosted — run it next to your ClickHouse with the same CLICKHOUSE_* connection vars on any of these targets:

• Docker — one docker run; the fastest path to a live dashboard.
• Cloudflare Workers — global edge deploy (how the demo at dash.chmonitor.dev runs).
• One-click templates — Railway, Render, Fly.io.
• Kubernetes (Helm) — for clusters.

Prefer to look before you install? Try the live demo above — no setup required.

Cloudflare Workers

This project supports deployment to Cloudflare Workers with static site generation and API routes.

Prerequisites: - Node.js 18+ and pnpm (bun is still used internally as the test runner and for .ts scripts) - Cloudflare Workers account - Wrangler CLI: npm install -g wrangler

Setup:

1. Clone and install dependencies:

git clone https://github.com/chmonitor/chmonitor.git
cd clickhouse-monitoring
pnpm install

1. Configure environment variables in .env.local:

CLICKHOUSE_HOST=https://your-clickhouse-host.com
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=yourpassword
CLICKHOUSE_TZ=UTC

Optional API-key protection for /api/v1/* routes:

CHM_API_KEY_SECRET=your-signing-secret

Optional Clerk UI/session support (set at build time; NEXT_PUBLIC_* is the v0.2 fallback):

CHM_AUTH_PROVIDER=clerk
VITE_AUTH_PROVIDER=clerk
VITE_CLERK_PUBLISHABLE_KEY=pk_live_your_key
CLERK_SECRET_KEY=sk_live_your_key

Feature permissions default to enabled and public. Add sparse overrides when a deployment should hide or protect a feature:

# /etc/clickhouse-monitor/config.toml
[features.agent]
access = "authenticated"

[features.metrics]
enabled = false

access = "guest" is accepted as an alias for access = "public".

CHM_CONFIG_FILE=/etc/clickhouse-monitor/config.toml
# or env-only:
CHM_FEATURE_AGENT_ACCESS=authenticated
CHM_DISABLED_FEATURES=settings,metrics

Leave auth provider env unset or set it to none for self-hosted deployments without auth.

1. Deploy to Cloudflare Workers:

# Set CLOUDFLARE_API_TOKEN in .env.production.local or export it
# OR use OAuth: npx wrangler login

# Unified deploy (config, build, deploy, cache — same as CI)
pnpm run cf:deploy

Manual Deployment Steps:

# Step by step (same as CI)
pnpm run cf:config        # Set secrets from .env.production.local
cd apps/dashboard
pnpm run build            # Vite build → native Workers bundle (+ tsc --noEmit)
wrangler deploy --minify

Important Notes: - Built with Vite + @cloudflare/vite-plugin into a native Workers bundle — no OpenNext, no KV/R2/D1 cache-population step - TanStack Start + React 19 (the v0.2 Next.js app was retired in v0.3) - Static shell is pre-rendered at build time; data is fetched client-side for edge CDN caching - API routes run on Workers using the Fetch API - Supports multi-host monitoring with query parameter routing (?host=0)

Docker

docker run -d \
  -p 3000:3000 \
  -e CLICKHOUSE_HOST=https://your-clickhouse-host.com \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=yourpassword \
  ghcr.io/chmonitor/chmonitor:latest

Releases

Tagged releases are built by GitHub Actions from tags matching v*. The release page includes:

• Docker images published to ghcr.io/chmonitor/chmonitor with the release version tag
• a Node.js standalone archive (*-standalone.tar.gz, the Nitro node-server output) for self-hosted Node deployments
• a Cloudflare Workers archive (*-cloudflare.tar.gz) for manual inspection or deployment
• generated release notes with CLI command usage, Docker tags, deployment steps, and checksums

For repeatable Docker deploys, prefer the versioned image tag from the release page instead of latest.

Upgrading to v0.3

v0.3 rebuilds the dashboard on TanStack Start. Features, routes, and ClickHouse setup carry over unchanged. The only env change is the browser variable prefix, and the old names keep working:

VITE_* vars are build-time inlined — set them when building the image/Worker, not only at runtime. Full per-platform steps: Migrate to v0.3.

Migrate your config with an AI assistant

Paste your current configuration (.env, docker-compose.yml, Helm values.yaml, or a k8s manifest) into any AI assistant with the prompt below. It applies the v0.3 rename rules and returns the migrated config plus a summary of what changed. This same prompt ships in every breaking-change GitHub Release and is kept in sync from .github/release-migration-prompt.md.

You are migrating a chmonitor deployment from v0.2 (Next.js) to v0.3 (TanStack Start).
Here is my current environment (.env / docker-compose / wrangler / k8s manifest):

<PASTE YOUR ENV HERE>

Rewrite it for v0.3 applying EXACTLY these rules, and output the migrated config
plus a short list of what you changed:

1. Rename every client var prefix NEXT_PUBLIC_ -> VITE_. Specifically:
   NEXT_PUBLIC_AUTH_PROVIDER          -> VITE_AUTH_PROVIDER
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY  -> VITE_CLERK_PUBLISHABLE_KEY
   NEXT_PUBLIC_FEATURE_CONVERSATION_DB-> VITE_FEATURE_CONVERSATION_DB
   (any other NEXT_PUBLIC_X -> VITE_X). The old names still work as a fallback.
2. Add server-side auth var CHM_AUTH_PROVIDER (none|clerk|proxy) mirroring the
   client provider. It is authoritative on the server; keep VITE_AUTH_PROVIDER too.
3. Do NOT rename server vars: CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD,
   CLICKHOUSE_NAME, CLICKHOUSE_MAX_EXECUTION_TIME, CLERK_SECRET_KEY, *_API_KEY — keep as-is.
4. VITE_* vars are build-time inlined: ensure they are present at image/Worker BUILD
   time (Docker build-args or CI build env), not only at container runtime.
5. If this is a Docker deployment, change the container start command from
   `node server.js` to `node server/index.mjs`. Port 3000 and the /api/healthz
   healthcheck are unchanged.
6. Flag anything that has no v0.3 equivalent instead of silently dropping it.

Documentation

• /docs - Full documentation site (local/docs)
• llms.txt - AI agent discovery file for automated code understanding
• https://zread.ai/chmonitor/chmonitor (AI Generated)
• https://docs.chmonitor.dev
• Getting Started
  • Local Development
  • User Role and Profile
  • Enable System Tables
• Deployments
  • Vercel
  • Docker
  • Kubernetes Helm Chart
  • One-Click Deploy — Railway / Render / Fly.io community templates
• Advanced
  • Telemetry — opt-in, privacy-first usage metrics (off by default)
  • Editions — open-core model: GPL-3.0 community is free forever; enterprise features gated by CHM_EDITION
• Reference
  • Platform Support Matrix — ClickHouse versions and distributions (supported / best-effort / untested)
  • Connection Presets — least-privilege read-only user setup for ClickHouse OSS, Altinity, and Cloud
  • Contributing a config / check — how to add a declarative monitoring check to the catalog
  • MCP Clients — connect Claude Desktop, Cursor, or any MCP client
  • Grafana Bridge — read chmonitor's ClickHouse from Grafana (community recipe)

AI Agent Access

llms.txt — standardized file that helps AI coding agents discover and understand the codebase structure. Access at https://your-domain.com/llms.txt or /llms.txt in local development.

MCP Server — exposes a Model Context Protocol endpoint at /api/mcp for AI tools to query your ClickHouse cluster directly. See docs/knowledge/mcp-server.md for setup.

Knowledge Graph — developer-facing notes in docs/knowledge/ with decisions, conventions, and architecture docs. See docs/knowledge/README.md for the index.

Screenshots

<source media="(prefers-color-scheme: dar