CH-UI

The open-source ClickHouse management platform.
SQL editor, dashboards, AI copilot, data pipelines, models, and admin — all in one binary. Free.

Documentation · Install · Pricing · Changelog

Why CH-UI?

Most ClickHouse tools give you a query box and call it a day. CH-UI gives you a full workspace — and almost everything is free and open source.

Download one binary. Run it. Get:

A multi-tab SQL editor with formatting, profiling, and streaming results
Dashboards with a drag-and-drop panel builder and multiple chart types
Brain — an AI assistant that understands your schema (OpenAI, Ollama, or any compatible provider)
Data pipelines — visual builder for Webhook, S3, Kafka, and DB sources into ClickHouse
Models — dbt-style SQL transformations with dependency graphs and scheduling
Admin panel — user management, connection management, provider configuration
Saved queries, schema explorer, connection management, and more

No Docker requirement. No external dependencies. No signup.

Features (Free)

Everything below is included in the free Community edition under Apache 2.0.

SQL Editor

Multi-tab interface with persistent state
CodeMirror 6 with SQL syntax highlighting and autocomplete
Query formatting and beautification
Streaming results via SSE — no timeout on long queries
Live query progress — elapsed time, percent complete, rows/bytes read and read throughput while the query is still running (needs SELECT on system.processes)
Query cost estimation — see estimated rows and parts to scan before running (like BigQuery's dry run)
Query profiling (pulls from system.query_log) with estimate vs actual accuracy comparison
Query plan analysis (EXPLAIN with parsed tree view)
Configurable max result rows and query timeout
Query parameters ({name:Type} bind params) in the editor

Schema Explorer

Full database/table/column tree browser
Table data preview with pagination
Column type introspection
Search across databases and tables

Dashboards

Create unlimited dashboards
Drag-and-drop panel builder
Multiple chart types (line, bar, scatter, area, and more via uplot)
Time range selector with presets (1h, 24h, 7d, 30d, custom)
Timezone support
Auto-refresh control
Each panel runs its own SQL query against your ClickHouse

Brain (AI Assistant)

Chat with your data using natural language
Multi-chat support with full history persistence
Provider support: OpenAI, OpenAI-compatible APIs (Groq, Together, etc.), Ollama (local LLMs)
Admin-controlled model and provider activation
Schema-aware context (attach up to 10 tables as context per chat)
SQL artifact generation — run generated queries directly from chat
Brain skills (configurable system prompts/instructions)
Token usage tracking

Data Pipelines

Visual pipeline canvas (drag-and-drop with XyFlow)
Source connectors: Webhook (inbound HTTP), Database (SQL query), S3, Kafka (with SCRAM auth)
Sink: ClickHouse (native insert with configurable batch size)
Pipeline start/stop controls
Run history, metrics, and error tracking
Real-time monitoring (rows ingested, bytes, batches, errors)

Models (SQL Transformations)

dbt-style SQL models with table, view, and incremental materialization
Model dependency graph (DAG visualization)
Execution with dependency ordering
Run history and results tracking
Table engine configuration per model
Run manually or on a cron schedule (model and pipeline schedules are free)

Saved Queries

Save queries with titles and descriptions
Sort by date, name, or query length
Filter, search, copy, and organize
Quick access from the sidebar

Admin Panel

User management (create, delete, assign roles)
ClickHouse user management (create users, update passwords, delete)
Connection management with multi-connection support
Brain provider and model configuration
Brain skill management
System statistics dashboard

Connections & Tunnel

Multi-connection support (manage multiple ClickHouse instances)
Secure WebSocket tunnel for remote ClickHouse access
Token-based agent authentication
Connection health monitoring
Install connector as OS service (ch-ui service install)

MCP Server

Embedded Model Context Protocol server at /mcp (streamable HTTP), in the same binary
Connect Claude Code, claude.ai, or Cursor with a revocable chm_ key; read-only tools for schema browsing, SELECT queries, and query plans
Server-side enforcement (readonly, row/time caps) + every AI query recorded in query history and the audit log
Pro: Query Insights and Cost Center exposed as structured tools
Docs: ch-ui.com/docs/mcp

Other

Dark mode
Session-based authentication with rate limiting
Security headers (CSP, X-Frame-Options, etc.)
Health check endpoint (/health)
Self-update (ch-ui update)
Shell completion generation

Community vs Pro

Almost everything is free. Pro adds production operations, governance and scheduling.

Capability	Community (Free)	Pro
SQL editor + explorer + formatting + profiling	Yes	Yes
Saved queries	Yes	Yes
Dashboards + panel builder	Yes	Yes
Brain (AI chat, multi-provider; Ask AI and agentic tools are Pro)	Yes	Yes
Data pipelines (Webhook, S3, Kafka, DB)	Yes	Yes
Models (SQL transformations, DAG, cron schedules)	Yes	Yes
Admin panel + user management	Yes	Yes
Multi-connection management	Yes	Yes
Tunnel (remote ClickHouse)	Yes	Yes
Query parameters in the editor (`{name:Type}` bind params)	Yes	Yes
Telemetry Logs, Sources, saved searches	Yes	Yes
MCP server (tools, write tools, OAuth, API keys)	Yes	Yes
Scheduled query jobs + cron + history + parameterized saved-query runs	-	Yes
Governance (metadata catalog, access matrix, policies, incidents, query audit, audit log viewer)	-	Yes
Policies + incidents + violations	-	Yes
Guardrails (query blocking in the editor and MCP)	-	Yes
Cluster Health (replication, Keeper, merges/mutations, parts pressure, long queries)	-	Yes
Query Insights	-	Yes
Cost Center	-	Yes
Performance regressions + saved before/after investigations	-	Yes
Fleet overview across connections	-	Yes
Incident timeline + deployment annotations	-	Yes
Schema comparison + downloadable SQL review plans	-	Yes
Weekly operations reports + configured email delivery	-	Yes
Alerting (SMTP, Resend, Brevo)	-	Yes
Telemetry Traces, Metrics, Service map, Monitors	-	Yes
Ask AI (text-to-SQL in the editor) + Brain agentic tools	-	Yes
GitHub sync for models	-	Yes
SSO (OIDC) with per-person roles and attribution	-	Yes
Audit forwarding to a SIEM (webhook, file, stdout)	-	Yes
MCP Pro tools (`query_insights_top`, `costs_summary`)	-	Yes
Command palette Pro search (entity search, scope prefixes)	-	Yes

See: ch-ui.com/docs/license

For the performance, fleet, schema comparison and weekly report workflows, see ch-ui.com/docs/performance.

Quick Start

1) Download

Linux (amd64):

curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-amd64
chmod +x ch-ui

Linux (arm64):

curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-arm64
chmod +x ch-ui

macOS (Apple Silicon):

curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-arm64
chmod +x ch-ui

macOS (Intel):

curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-amd64
chmod +x ch-ui

Optional — verify checksum:

curl -L -o checksums.txt https://github.com/caioricciuti/ch-ui/releases/latest/download/checksums.txt
sha256sum -c checksums.txt --ignore-missing

2) Run

sudo install -m 755 ch-ui /usr/local/bin/ch-ui
ch-ui

Or just ./ch-ui from the download folder.

Open http://localhost:3488 and log in with your ClickHouse credentials.

Quick Start (Docker)

docker run --rm \
  -p 3488:3488 \
  -v ch-ui-data:/app/data \
  -e CLICKHOUSE_URL=http://host.docker.internal:8123 \
  ghcr.io/caioricciuti/ch-ui:latest

On Linux, replace host.docker.internal with a host/IP reachable from the container.
Persisted state is stored in /app/data/ch-ui.db (volume: ch-ui-data).

Architecture

CH-UI ships as a single binary with two operating modes:

server — web app + API + WebSocket tunnel gateway (default)
connect — lightweight agent that exposes local ClickHouse over secure WebSocket

flowchart LR
    U["Browser"] --> S["CH-UI Server\n(UI + API + Gateway)"]
    S <--> DB["SQLite\n(state, settings, chats, dashboards)"]
    A["ch-ui connect\n(Agent)"] <--> S
    A --> CH["ClickHouse"]

For local use, the server starts an embedded connector automatically against localhost:8123.

Tech stack: Go backend (chi v5, SQLite WAL mode), Svelte 5 frontend (TypeScript, Vite, TailwindCSS), embedded at build time.

Remote ClickHouse (Tunnel)

Connect to ClickHouse instances running on other machines using the secure WebSocket tunnel.

Server (VM2):

ch-ui server --port 3488

Agent (VM1, where ClickHouse runs):

ch-ui connect --url wss://your-ch-ui-domain/connect --key cht_your_tunnel_token

Tunnel key management

Run these on the server host:

ch-ui tunnel create --name "vm1-clickhouse"   # Create connection + key
ch-ui tunnel list                              # List all connections
ch-ui tunnel show <connection-id>              # Show token + setup commands
ch-ui tunnel rotate <connection-id>            # Rotate token (old one invalidated)
ch-ui tunnel delete <connection-id>            # Delete connection

Token can also be generated from the Admin UI.
Agent only needs outbound access to the server's /connect endpoint.
Add --takeover to replace a stale agent session.
Install as OS service: ch-ui service install --key cht_xxx --url wss://host/connect

For full hardening guide: ch-ui.com/docs/deployment

CLI Reference

Quick start commands

ch-ui                     # Start server (local ClickHouse)
ch-ui server start --detach  # Start in background
ch-ui server status          # Check if running
ch-ui server stop            # Stop server

Full command map

Command	Description
`ch-ui` / `ch-ui server`	Start web app + API + gateway
`ch-ui connect`	Start tunnel agent next to ClickHouse
`ch-ui tunnel create/list/show/rotate/delete`	Manage tunnel keys (server host)
`ch-ui service install/start/stop/status/logs/uninstall`	Manage connector as OS service
`ch-ui backup [file]`	Consistent snapshot of the SQLite database
`ch-ui update`	Update to latest release
`ch-ui version`	Print version
`ch-ui completion bash/zsh/fish`	Generate shell completions
`ch-ui uninstall`	Remove CH-UI from system

Server flags

Flag	Default	Description
`--port, -p`	`3488`	HTTP port
`--clickhouse-url`	`http://localhost:8123`	Local ClickHouse URL
`--connection-name`	`Local ClickHouse`	Display name for local connection
`--config, -c`	-	Path to `server.yaml`
`--detach`	-	Run in background
`--dev`	-	Development mode (proxy to Vite)

Connect flags

Flag	Default	Description
`--url`	-	WebSocket tunnel URL (`wss://`)
`--key`	-	Tunnel token (`cht_...`)
`--clickhouse-url`	`http://localhost:8123`	Local ClickHouse
`--config, -c`	-	Path to `config.yaml`
`--detach`	-	Run in background
`--takeover`	-	Replace stale agent session

Configuration

CH-UI works without config files. You only need them for production defaults or service-managed startup.

Config file locations

File	macOS	Linux
`server.yaml`	`~/.config/ch-ui/server.yaml`	`/etc/ch-ui/server.yaml`
`config.yaml`	`~/.config/ch-ui/config.yaml`	`/etc/ch-ui/config.yaml`

Priority: CLI flags > environment variables > config file > built-in defaults

Server config

port: 3488
app_url: https://ch-ui.yourcompany.com
database_path: /var/lib/ch-ui/ch-ui.db
clickhouse_url: http://localhost:8123
connection_name: Local ClickHouse
app_secret_key: "change-this-in-production"
allowed_origins:
  - https://ch-ui.yourcompany.com

Key	Env var	Default	Description
`port`	`PORT`	`3488`	HTTP port
`app_url`	`APP_URL`	`http://localhost:<port>`	Public URL for links and tunnel inference
`database_path`	`DATABASE_PATH`	`./data/ch-ui.db`	SQLite database location
`clickhouse_url`	`CLICKHOUSE_URL`	`http://localhost:8123`	Embedded local connection target
`connection_name`	`CONNECTION_NAME`	`Local ClickHouse`	Display name for local connection
`app_secret_key`	`APP_SECRET_KEY`	auto-generated	Encrypts sessions and stored credentials. When not set, a random key is generated and persisted to `.app_secret_key` next to the database
`allowed_origins`	`ALLOWED_ORIGINS`	empty	CORS allowlist (comma-separated in env)
`tunnel_url`	`TUNNEL_URL`	derived from port	Tunnel endpoint advertised to agents

Connector config

tunnel_token: "cht_your_token"
clickhouse_url: "http://127.0.0.1:8123"
tunnel_url: "wss://your-ch-ui-domain/connect"

Key	Env var	Default	Description
`tunnel_token`	`TUNNEL_TOKEN`	required	Auth key from `ch-ui tunnel create`
`clickhouse_url`	`CLICKHOUSE_URL`	`http://localhost:8123`	Local ClickHouse
`tunnel_url`	`TUNNEL_URL`	`ws://127.0.0.1:3488/connect`	Server gateway endpoint

Changing the local ClickHouse URL

# CLI flag
ch-ui server --clickhouse-url http://127.0.0.1:8123

# Environment variable
CLICKHOUSE_URL=http://127.0.0.1:8123 ch-ui server

# With custom connection name
ch-ui server --clickhouse-url http://127.0.0.1:8123 --connection-name "My ClickHouse"

The login page also has a Can't login? button that shows setup guidance.

CH-UI can connect to ClickHouse either directly (point CLICKHOUSE_URL at the endpoint, including a reverse-proxied https:// one) or via an outbound tunnel that keeps ClickHouse fully private. See ch-ui.com/docs/connections.

Production Checklist

Set a strong APP_SECRET_KEY
Set APP_URL to your public HTTPS URL
Configure ALLOWED_ORIGINS
Put CH-UI behind a TLS reverse proxy (Nginx example: ch-ui.conf)
Ensure WebSocket upgrade support for /connect
Back up the SQLite database regularly with ch-ui backup, and keep APP_SECRET_KEY safe
Run connector as OS service on remote hosts

Backup and restore

# Backup: consistent snapshot, safe while the server is running
ch-ui backup /var/backups/ch-ui-$(date +%F).db -c /etc/ch-ui/server.yaml

# Restore: stop the server, replace the DB file with the backup, start it
# again with the same APP_SECRET_KEY

Do not cp the live database: it runs in WAL mode and a plain copy can be inconsistent. The backup holds credentials encrypted with APP_SECRET_KEY, so back up that key too (or the .app_secret_key file next to the database when the key was auto-generated). A backup is useless without it.

Troubleshooting

Port already in use

ch-ui server status   # Check if already running
ch-ui server stop     # Stop the old process

Can't log in

Authentication failed — wrong ClickHouse credentials
Connection unavailable — wrong URL or connector offline
Too many attempts — wait for retry window; fix URL first if needed

Click Can't login? on the login page for guided recovery, or restart with:

ch-ui server --clickhouse-url 'http://127.0.0.1:8123'

Full guide: ch-ui.com/docs/cant-login

Connector auth fails (`invalid token`)

Verify you copied the latest cht_... token
Check with ch-ui tunnel list
Rotate with ch-ui tunnel rotate <connection-id>

WebSocket fails behind proxy

Your proxy must forward upgrades on /connect:

Upgrade and Connection: upgrade headers
Long read/send timeouts
Buffering disabled for tunnel path

Health check

curl http://localhost:3488/health

Development

Requirements: Go 1.25+, Bun

git clone https://github.com/caioricciuti/ch-ui.git
cd ch-ui
make build    # Full production build (frontend + Go binary)
./ch-ui

Dev mode (two terminals):

make dev                              # Terminal 1: Go server
cd ui && bun install && bun run dev   # Terminal 2: Vite dev server

Useful targets: make build | make test | make vet | make clean | make rebuild

Upgrade

ch-ui update

Downloads the latest release for your OS/arch, verifies checksum, and replaces the binary.

Legal

CH-UI is dual-licensed:

Community core — Apache 2.0. Free to use, modify, and distribute.
Pro features — Business Source License 1.1 (LICENSE.BSL). Source-available; production use requires a valid CH-UI Pro license; converts to Apache 2.0 on the Change Date. Every Pro source file carries an SPDX-License-Identifier: BUSL-1.1 header; see LICENSING.md for the authoritative scope.
Licensing details: ch-ui.com/docs/license
Terms: ch-ui.com/terms
Privacy: ch-ui.com/privacy

Contributing

Issues and PRs are welcome.

When contributing, please include:

Reproduction steps (for bugs)
Expected behavior
Migration notes (if schema/API changed)
Screenshots (for UI changes)

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.github		.github
cmd		cmd
connector		connector
deploy/helm/ch-ui		deploy/helm/ch-ui
integrations/claude-code-plugin		integrations/claude-code-plugin
internal		internal
license		license
site		site
ui		ui
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE.BSL		LICENSE.BSL
LICENSE.md		LICENSE.md
LICENSING.md		LICENSING.md
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
VERSION		VERSION
ch-ui.conf		ch-ui.conf
docker-compose.yml		docker-compose.yml
frontend.go		frontend.go
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Latest commit

History

Folders and files

Repository files navigation