CH-UI

The open-source ClickHouse management platform.

SQL editor, dashboards, AI copilot, data pipelines, models, and admin — all in one binary. Free.

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.

Table of Contents

• Features (Free)
• Community vs Pro
• Quick Start
• Quick Start (Docker)
• CH-UI Cloud
• Architecture
• Remote ClickHouse (Tunnel)
• CLI Reference
• Configuration
• Production Checklist
• Troubleshooting
• Development
• Upgrade
• Legal
• Contributing

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
• 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
• Guardrails enforcement (query validation before execution)

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
• Can be scheduled via the scheduler (Pro) or run manually

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)

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 enterprise governance and scheduling.

See: docs/license.md

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).

CH-UI Cloud

Don't want to self-host? CH-UI Cloud is the managed version — same features, zero infrastructure.

Connect your ClickHouse to the cloud using the lightweight chui-agent:

curl -fsSL https://console.ch-ui.com/install.sh | sh

Then connect:

chui-agent --url wss://yourorg.ch-ui.com/connect --key cht_your_token

chui-agent is a standalone 6MB binary — no server, no root, no config files. Get your token from the CH-UI Cloud console.

Note: chui-agent is for CH-UI Cloud only. For self-hosted tunnel connections, use ch-ui connect (see Remote ClickHouse (Tunnel) below).

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: docs/production-runbook.md

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

Server flags

Connect flags

Configuration

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

Config file locations

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

Connector config

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