Introduction

CH-UI is a self-hosted ClickHouse control plane that combines SQL editing, governance, AI copilot, scheduling, and admin operations in one binary.

No Docker requirement. No extra backend services required to start.

Who is this for?

CH-UI is the governance layer for teams that run ClickHouse themselves. You will get the most out of it if any of the following describe you:

• You have 20+ analysts and can’t manage ClickHouse users manually. Create ClickHouse users, assign roles, and review the full access matrix (direct and role-based grants) from a single UI instead of a pile of CREATE USER / GRANT scripts.
• Your compliance team needs audit logs for every query against PII. Tag tables and columns as PII, capture every query in the query log, and record privileged actions in a separate audit log with filtering and search.
• You run ClickHouse on-prem for data residency and need operator tooling. The tunnel connector reaches remote ClickHouse without exposing it, policies enforce warn/block rules, and incidents + lineage + scheduled queries give you the rest of the operator surface.

If you’re a single developer prototyping against a local ClickHouse, Community is plenty. The governance suite starts to matter once a team and a compliance surface exist around your warehouse.

Why Teams Use CH-UI

• Fast setup: download binary, run, open browser
• Real operations: status, restart/stop, connector lifecycle, sync visibility
• Production flow: tunnel architecture for remote ClickHouse
• Governance value: lineage, incidents, policies, access matrix
• AI that is practical: model/provider control, persisted chats, SQL-aware artifacts

Community vs Pro

Core Capabilities

Community (Apache 2.0)

• SQL editor + result views
• Database/table explorer
• Saved queries
• Dashboards and panel builder
• Pipelines (visual ingestion from Kafka, webhooks, databases, S3)
• Models (SQL transformations with DAG execution and scheduling)
• Brain (multi-chat, model/provider management, artifacts)
• Admin (users, tunnels, providers)
• Local-first single-binary runtime
• Tunnel connector for remote ClickHouse instances

Pro (license required)

• Schedules and execution history
• Governance (metadata, access, incidents, policies, lineage)
• Alerts (SMTP, Resend, Brevo) for governance events
• Query log and audit log

Quick Start

# Install CH-UI (Linux / macOS)
curl -fsSL https://ch-ui.com/install.sh | sh

# Start CH-UI (defaults to server mode)
ch-ui

# Open UI
# http://localhost:3488

Docker alternative:

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

If login fails during first run, use the recovery guide: Can't login?

Runtime Model

CH-UI has two operating modes:

1. ch-ui server - UI, API, scheduler, governance syncers, and tunnel gateway.
2. ch-ui connect - lightweight agent that exposes a ClickHouse instance over secure WebSocket.

This lets you run CH-UI on one VM and ClickHouse on another VM while keeping only outbound tunnel traffic from the ClickHouse host.

Next Steps