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

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)
• Community vs Pro
• Quick Start
• Quick Start (Docker)
• Architecture
• Remote ClickHouse (Tunnel)
• CLI Reference
• Configuration
• Production Checklist
• Troubleshooting
• Development
• Upgrade
• Legal
• Contributing

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

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

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

• 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

• 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
• Langfuse integration for LLM observability

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

• 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

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

• 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
• Langfuse integration settings
• System statistics dashboard

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

• 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

Almost everything is free. Pro adds enterprise governance and scheduling.

See: docs/license.md

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

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.

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

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

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

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

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

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

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

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

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

• 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 SQLite database regularly
• Run connector as OS service on remote hosts

# Backup
cp /var/lib/ch-ui/ch-ui.db /var/backups/ch-ui-$(date +%F).db

# Restore — stop server first, then replace the DB file

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

• 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: docs/cant-login.md

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

Your proxy must forward upgrades on /connect:

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

curl http://localhost:3488/health

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

ch-ui update

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

• Core license: LICENSE (Apache 2.0)
• Licensing details: docs/license.md
• Terms: docs/legal/terms-of-service.md
• Privacy: docs/legal/privacy-policy.md

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)

Launches a full CH-UI + ClickHouse environment in your browser. No install required. Free tier: 50 hours/month, no credit card - Via Gitpod (https://www.gitpod.io/)