ch-ui
Use CH-UI to work with your data from Click House self-hosted with a user-friendly interface. CH-UI is a modern and feature-rich user interface for ClickHouse databases. It offers an intuitive platform for querying ClickHouse databases, executing queries, and visualizing metrics about your instance.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/caioricciuti/ch-ui with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/caioricciuti/ch-ui'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/caioricciuti--ch-ui)HTML
<a href="/listings/caioricciuti--ch-ui"><img src="/api/listings/caioricciuti--ch-ui/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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
Windows (PowerShell):
# x64 Invoke-WebRequest -OutFile ch-ui.exe https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-windows-amd64.exe # ARM Invoke-WebRequest -OutFile ch-ui.exe https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-windows-arm64.exe
The Windows binary is not code signed, so SmartScreen may warn the first time you run it. Compare `Get-FileHash ch-ui.exe -Algorithm SHA256` with the matching line in `checksums.txt`.
Optional: verify checksum (Linux, macOS):
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.
On Windows, double-click `ch-ui.exe` (or run `.\ch-ui.exe`): with no arguments it starts desktop mode and opens your browser. Close its console window to stop it. Run `.\ch-ui.exe server` for a team server.
Just for yourself: desktop mode
ch-ui desktop
Listens on `127.0.0.1` only, keeps the database and secret key in your user data folder (`~/Library/Application Support/ch-ui` on macOS, `%AppData%\ch-ui` on Windows, `$XDG_CONFIG_HOME/ch-ui` or `~/.config/ch-ui` on Linux), uses port 3488 or any free port, and opens your browser. Running it again opens the instance already running. See [ch-ui.com/docs/installation](https://ch-ui.com/docs/installation#desktop-personal-use).
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 18 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "ch-ui",
- "owner": { "name": "Caio Ricciuti", "url": "https://github.com/caioricciuti" },
- "metadata": {
- "description": "Plugins for CH-UI, the self-hosted ClickHouse console.",
- "version": "1.0.0"
- },
- "plugins": [
- {
- "name": "ch-ui",
- "source": "./integrations/claude-code-plugin",
- "description": "CH-UI MCP server connection plus a ClickHouse analytics skill.",
- "version": "1.0.0",
- "category": "database",
- "keywords": ["clickhouse", "sql", "analytics", "mcp"]
- }
- ]
- }
README.md · README · 697 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <p align="center">
- <img src="ui/src/assets/logo.png" alt="CH-UI Logo" width="88" />
- </p>
- <h1 align="center">CH-UI</h1>
- <p align="center">
- <strong>The open-source ClickHouse management platform.</strong><br/>
- SQL editor, dashboards, AI copilot, data pipelines and ingest, telemetry, models, and admin, all in one binary. Free.
- </p>
- <p align="center">
- <a href="https://github.com/caioricciuti/ch-ui/releases"><img src="https://img.shields.io/github/v/release/caioricciuti/ch-ui?label=version" alt="Version" /></a>
- <a href="https://github.com/caioricciuti/ch-ui/blob/main/LICENSING.md"><img src="https://img.shields.io/badge/license-Apache%202.0%20%2B%20BSL%201.1%20(Pro)-blue" alt="License: Apache 2.0, Pro features BSL 1.1" /></a>
- <a href="https://github.com/caioricciuti/ch-ui/stargazers"><img src="https://img.shields.io/github/stars/caioricciuti/ch-ui" alt="Stars" /></a>
- <a href="https://github.com/caioricciuti/ch-ui/pkgs/container/ch-ui"><img src="https://img.shields.io/badge/docker-ghcr.io-blue" alt="Docker" /></a>
- </p>
- <p align="center">
- <a href="https://ch-ui.com/docs"><strong>Documentation</strong></a> ·
- <a href="https://ch-ui.com/docs/installation">Install</a> ·
- <a href="https://ch-ui.com/pricing">Pricing</a> ·
- <a href="https://ch-ui.com/docs/changelog">Changelog</a>
- </p>
- ---
- ## 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 (Anthropic, OpenAI, Ollama, or any OpenAI-compatible provider)
- - **Data pipelines**: visual builder for Webhook, Ingest, S3, Kafka, and DB sources into ClickHouse, with Parse, Map fields and Filter transforms
- - **Ingest**: CH-UI receives OpenTelemetry logs and traces, JSON events, Elasticsearch bulk requests and Splunk HEC events itself, spools them on disk and writes them to ClickHouse
- - **Telemetry**: search OpenTelemetry logs in ClickHouse, whether your collector writes them or CH-UI received them (traces, metrics and the service map with Pro)
- - **Models**: dbt-style SQL transformations with dependency graphs and scheduling
- - **Data lineage**: how data flows between tables, materialized views, views and dictionaries
- - **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)](#features-free)
- - [Community vs Pro](#community-vs-pro)
- - [Quick Start](#quick-start)
- - [Quick Start (Docker)](#quick-start-docker)
- - [Architecture](#architecture)
- - [Remote ClickHouse (Tunnel)](#remote-clickhouse-tunnel)
- - [CLI Reference](#cli-reference)
- - [Configuration](#configuration)
- - [Production Checklist](#production-checklist)
- - [Troubleshooting](#troubleshooting)
- - [Development](#development)
- - [Upgrade](#upgrade)
- - [Legal](#legal)
- - [Contributing](#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
- - **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
- - Panel types: table, stat, gauge, time series (line, area, stacked), bar, pie, histogram, scatter, heatmap and Markdown text
- - Drilldown links: click a value to filter the dashboard, open another dashboard, open a filled-in query, or open a URL
- - 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:** Anthropic, OpenAI, OpenAI-compatible APIs (Azure, OpenRouter, Groq, Together, vLLM, etc.), Ollama (local LLMs)
- - Admin-controlled model and provider activation
- - Schema-aware context: type `@` to mention tables, dashboards, pipelines, models or saved queries in a message
- - SQL artifact generation: run generated queries directly from chat
- - Brain skills (configurable system prompts/instructions)
- - Global token budgets (per person, per role and dollar budgets are Pro)
- ### Data Pipelines
- - Visual pipeline canvas (drag-and-drop with XyFlow)
- - **Source connectors:** Webhook (inbound HTTP), Ingest (OTLP, JSON events, Elasticsearch bulk, Splunk HEC), Database (SQL query), S3, Kafka (with SCRAM auth)
- - **Transforms:** Parse (JSON, logfmt, regex, nginx/Apache access logs, syslog), Map fields and Filter are free; Sample, Redact and Route (up to 8 sinks per pipeline) are Pro
- - **Preview** on every transform node: records before and after the chain, dropped records with the reason, parse errors
- - **Sink:** ClickHouse, with a dead-letter table for refused rows
- - **Table layouts** for auto-created tables: Custom from data, Wide events (`timestamp`, `service`, `level`, `message`, `trace_id`, `attributes`), OpenTelemetry logs, OpenTelemetry traces
- - **Durable webhook:** every request is written to an on-disk spool before the `200`, so a ClickHouse outage or a restart loses nothing that was acknowledged
- - Pipeline start/stop controls
- - Run history, metrics, and error tracking
- - Real-time monitoring (rows ingested, bytes, batches, errors, per-node counters)
- - Docs: [ch-ui.com/docs/pipelines](https://ch-ui.com/docs/pipelines)
- ### Ingest
- - Receivers built into the binary: `POST /ingest/v1/logs` and `/ingest/v1/traces` (OTLP over HTTP, protobuf or JSON), `/ingest/v1/events` (JSON object, array or NDJSON), `/ingest/es` (Elasticsearch bulk API) and `/ingest/services/collector` (Splunk HEC)
- - Works with the OpenTelemetry Collector, OTel SDKs, Vector, Fluent Bit, Filebeat, Logstash, Splunk HEC clients and plain `curl`
- - Per-pipeline ingest keys (`chi_...`), stored hashed, shown once, revocable; per-key rate limit and per-pipeline daily quota
- - Requests are fsynced to a spool in `<data dir>/ingest-spool` before they are answered, then written to ClickHouse with a stable deduplication token
- - Logs and traces land in the OpenTelemetry exporter's table layout, so Telemetry reads them with no extra setup
- - **Send data here** panel in the pipeline editor fills in shipper configs with your URL and key
- - Optional separate listener (`--ingest-addr :4318`) for shipper traffic
- - Docs: [ch-ui.com/docs/ingest](https://ch-ui.com/docs/ingest/)
- ### Telemetry
- - Logs explorer over OpenTelemetry data in ClickHouse: search syntax, histograms, facets, surrounding context, logs by trace
- - Sources: detect the exporter's tables or map your own; saved searches
- - Nothing copied or indexed elsewhere, every screen is SQL against your tables
- - Pro: Traces, Metrics, Service map and Monitors
- - Docs: [ch-ui.com/docs/telemetry](https://ch-ui.com/docs/telemetry)
- ### 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)
- ### Data Lineage
- - See how data flows between tables, materialized views, views, dictionaries and external sources (Kafka, S3, URL, MySQL and table functions)
- - **Explore › Lineage** with database picker, focus search, 1 to 4 hops and kind filters; a Lineage view on every table page
- - Read on demand with your own ClickHouse account from system tables, cached for 30 seconds, never reads `query_log`
- - Docs: [ch-ui.com/docs/lineage](https://ch-ui.com/docs/lineage)
- ### 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`, Linux and macOS)
- ### MCP Server
- - Embedded [Model Context Protocol](https://modelcontextprotocol.io) server at `/mcp` (streamable HTTP), in the same binary
- - Connect Claude Code, claude.ai, ChatGPT, Cursor or VS Code with OAuth sign-in or a revocable `chm_` key
- - Read tools by default: schema browsing, SELECT queries, saved queries, query plans, telemetry logs, lineage, model and pipeline status
- - Opt-in permissions: write (saved queries, dashboards, draft models and pipelines) and lifecycle actions (run models, start and stop pipelines), each confirmed in the client when it supports prompts
- - Server-side enforcement (`readonly`, row/time caps, database allowlist) + every AI call recorded in the audit log
- - Pro: alerts, schedules, reports, cluster health, Query Insights, Cost Center, traces and metrics tools, and running schedules and reports now
- - Docs: [ch-ui.com/docs/mcp](https://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`)
- - Personal desktop mode (`ch-ui desktop`): loopback only, data in your user folder, opens the browser
- - Binaries for Linux, macOS and Windows (amd64 and arm64)
- - 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, Ingest, S3, Kafka, DB) | **Yes** | Yes |
- | Ingest receivers (OTLP logs and traces, JSON events, Elasticsearch bulk, Splunk HEC), ingest keys, durable spool | **Yes** | Yes |
- | Pipeline transforms Parse, Map fields, Filter, with preview | **Yes** | Yes |
- | Table layouts (Custom, Wide events, OpenTelemetry logs and traces) | **Yes** | Yes |
- | Models (SQL transformations, DAG, cron schedules) | **Yes** | Yes |
- | Admin panel + user management | **Yes** | Yes |
- | Multi-connection management | **Yes** | Yes |
- | Data lineage | **Yes** | Yes |
- | Desktop mode (`ch-ui desktop`) and Linux, macOS, Windows binaries | **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 (read tools, write tools, lifecycle actions, OAuth, API keys) | **Yes** | Yes |
- | Pipeline Sample, Redact and Route (up to 8 sinks per pipeline) | - | **Yes** |
- | Scheduled query jobs + cron + history + parameterized saved-query runs | - | **Yes** |
- | Scheduled reports (saved query results and dashboard summaries to email, Slack, Teams, webhooks) | - | **Yes** |
- | Governance (metadata catalog, access matrix, policies, incidents, query audit, audit log viewer) | - | **Yes** |
- | Policies + incidents + violations | - | **Yes** |
- | ClickHouse access control editor, access history and drift | - | **Yes** |
- | Access as code (export/import roles, grants, policies, quotas, profiles; create users on import) | - | **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, Slack, Teams, webhooks), incl. ingest and pipeline alerts | - | **Yes** |
- | Telemetry Traces, Metrics, Service map, Monitors | - | **Yes** |
- | Ask AI (text-to-SQL in the editor) + Brain agentic tools | - | **Yes** |
- | Brain budgets per person and per role, dollar limits | - | **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 (operations, Query Insights, Cost Center, traces and metrics, schedule and report actions) | - | **Yes** |
- | Command palette Pro search (entity search, scope prefixes) | - | **Yes** |
- See: [ch-ui.com/docs/license](https://ch-ui.com/docs/license)
- Pipelines with Sample, Redact or Route nodes save on any edition; running or
- previewing them without Pro fails with `402` and names the node.
- For the performance, fleet, schema comparison and weekly report workflows, see
- [ch-ui.com/docs/performance](https://ch-ui.com/docs/performance).
- ---
- ## Quick Start
- ### 1) Download
- Linux (amd64):
- ```bash
- curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-amd64
- chmod +x ch-ui
- ```
- Linux (arm64):
- ```bash
- 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):
- ```bash
- curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-arm64
- chmod +x ch-ui
- ```
- macOS (Intel):
- ```bash
- curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-amd64
- chmod +x ch-ui
- ```
- Windows (PowerShell):
- ```powershell
- # x64
- Invoke-WebRequest -OutFile ch-ui.exe https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-windows-amd64.exe
- # ARM
- Invoke-WebRequest -OutFile ch-ui.exe https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-windows-arm64.exe
- ```
- The Windows binary is not code signed, so SmartScreen may warn the first time
- you run it. Compare `Get-FileHash ch-ui.exe -Algorithm SHA256` with the
- matching line in `checksums.txt`.
- Optional: verify checksum (Linux, macOS):
- ```bash
- curl -L -o checksums.txt https://github.com/caioricciuti/ch-ui/releases/latest/download/checksums.txt
- sha256sum -c checksums.txt --ignore-missing
- ```
- ### 2) Run
- ```bash
- 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.
- On Windows, double-click `ch-ui.exe` (or run `.\ch-ui.exe`): with no arguments
- it starts desktop mode and opens your browser. Close its console window to stop
- it. Run `.\ch-ui.exe server` for a team server.
- ### Just for yourself: desktop mode
- ```bash
- ch-ui desktop
- ```
- Listens on `127.0.0.1` only, keeps the database and secret key in your user
- data folder (`~/Library/Application Support/ch-ui` on macOS,
- `%AppData%\ch-ui` on Windows, `$XDG_CONFIG_HOME/ch-ui` or `~/.config/ch-ui` on
- Linux), uses port 3488 or any free port, and opens your browser.
- Running it again opens the instance already running. See
- [ch-ui.com/docs/installation](https://ch-ui.com/docs/installation#desktop-personal-use).
- ---
- ## Quick Start (Docker)
- ```bash
- 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 three operating modes:
- - **`server`**: web app + API + WebSocket tunnel gateway + ingest receivers (default on Linux and macOS)
- - **`desktop`**: the same app for one person, on `127.0.0.1` only (default on Windows)
- - **`connect`**: lightweight agent that exposes local ClickHouse over secure WebSocket
- ```mermaid
- flowchart LR
- U["Browser"] --> S["CH-UI Server\n(UI + API + Gateway)"]
- SH["Shippers\n(OTel, Vector, Fluent Bit, ...)"] -->|"/ingest"| S
- S <--> DB["SQLite + ingest spool\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):**
- ```bash
- ch-ui server --port 3488
- ```
- **Agent (VM1, where ClickHouse runs):**
- ```bash
- ch-ui connect --url wss://your-ch-ui-domain/connect --key cht_your_tunnel_token
- ```
- ### Tunnel key management
- Run these on the server host:
- ```bash
- 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](https://ch-ui.com/docs/deployment)
- ---
- ## CLI Reference
- ### Quick start commands
- ```bash
- ch-ui # Start server (local ClickHouse); desktop mode on Windows
- ch-ui desktop # Run for yourself on 127.0.0.1 and open the browser
- 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 + ingest receivers (`ch-ui` alone runs `desktop` on Windows) |
- | `ch-ui desktop` | Run CH-UI for yourself on this computer, loopback only, and open the browser |
- | `ch-ui connect` | Start tunnel agent next to ClickHouse |
- | `ch-ui tunnel create/list/show/rotate/delete` | Manage tunnel keys (server host) |
- | `ch-ui server start/stop/status/restart` | Run the server in the background and manage it through its PID file |
- | `ch-ui service install/start/stop/restart/status/logs/uninstall` | Manage connector as OS service (Linux and macOS; not supported on Windows yet) |
- | `ch-ui backup [file]` | Consistent snapshot of the SQLite database |
- | `ch-ui reset-admin [--user <name>] [--connection <id-or-name>]` | Recover the CH-UI admin role when no admin can sign in |
- | `ch-ui update` | Update to latest release (restarts a running server; `--pid-file`, `--stop-timeout`, `--restart-server`) |
- | `ch-ui version` | Print version |
- | `ch-ui completion bash/zsh/fish/powershell` | Generate shell completions |
- | `ch-ui uninstall` | Remove CH-UI from system (stops a running `desktop`, keeps its data folder; `--print-only` to preview) |
- ### 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) |
- | `--allow-login-url` | off | Let the login page sign in with a typed ClickHouse URL. The server makes the connection, so enable only on trusted networks |
- | `--trusted-proxies` | loopback, private and link-local ranges | Comma-separated IPs or CIDRs of reverse proxies whose X-Forwarded-For is trusted; `none` trusts no proxy |
- | `--ingest-addr` | off | Also serve the `/ingest` receivers (and `/v1` OTLP aliases) on this address, e.g. `:4318` |
- | `--pid-file` | `ch-ui-server.pid` | Path to server PID file |
- | `--stop-timeout` | `10s` | Graceful stop timeout |
- `ch-ui server restart` runs in the background by default (`--detach=false` to
- stay in the foreground).
- ### Desktop flags
- | Flag | Default | Description |
- |---|---|---|
- | `--port, -p` | `3488` | Port; if the default is taken, any free port is used. An explicit port fails when taken |
- | `--host` | `127.0.0.1` | Loopback address (`127.0.0.1`, `::1` or `localhost`) |
- | `--no-browser` | - | Do not open the browser |
- | `--clickhouse-url` | `http://localhost:8123` | Local ClickHouse URL |
- | `--connection-name` | `Local ClickHouse` | Display name for local connection |
- | `--config, -c` | - | Path to `server.yaml` |
- `DATABASE_PATH` and `APP_SECRET_KEY` override the database and key as they do
- for `ch-ui server`.
- ### Connect flags
- | Flag | Default | Description |
- |---|---|---|
- | `--url` | `ws://127.0.0.1:3488/connect` | WebSocket tunnel URL (`ws://` or `wss://`); falls back to `TUNNEL_URL`, then the config file |
- | `--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 | Windows |
- |---|---|---|---|
- | `server.yaml` | `~/.config/ch-ui/server.yaml` | `/etc/ch-ui/server.yaml` | pass `--config` |
- | `config.yaml` | `~/.config/ch-ui/config.yaml` | `/etc/ch-ui/config.yaml` | `%AppData%\ch-ui\connect\config.yaml` |
- **Priority:** CLI flags > environment variables > config file > built-in defaults
- ### Server config
- ```yaml
- 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 |
- | `app_secret_key_previous` | `APP_SECRET_KEY_PREVIOUS` | empty | The key in use before a rotation. Stored secrets decrypt with it as a fallback, and startup re-encrypts them with the current key |
- | `allowed_origins` | `ALLOWED_ORIGINS` | empty | CORS allowlist (comma-separated in env) |
- | `tunnel_url` | `TUNNEL_URL` | derived from port | Tunnel endpoint advertised to agents |
- | `session_max_age` | `SESSION_MAX_AGE` | `604800` (7 days) | Session lifetime in seconds |
- | `allow_login_url` | `ALLOW_LOGIN_URL` | `false` | Same as `--allow-login-url` |
- | `trusted_proxies` | `TRUSTED_PROXIES` | loopback, private and link-local ranges | Same as `--trusted-proxies` (list in YAML, comma-separated in env) |
- | `tls_cert_file` / `tls_key_file` | `TLS_CERT_FILE` / `TLS_KEY_FILE` | empty | Set both to serve HTTPS directly; otherwise put a TLS-terminating proxy in front |
- | `export_max_bytes` / `export_max_rows` | `EXPORT_MAX_BYTES` / `EXPORT_MAX_ROWS` | 1 GiB / 10,000,000 | Caps on one full result export |
- | `ingest_addr` | `INGEST_ADDR` | off | Same as `--ingest-addr` |
- | `ingest_only_separate` | `INGEST_ONLY_SEPARATE` | `false` | With `ingest_addr` set, stop serving `/ingest` on the main port |
- | `ingest_spool_max_bytes` | `INGEST_SPOOL_MAX_BYTES` | 2 GiB | Cap on the on-disk ingest spool (`<data dir>/ingest-spool`), shared by ingest and webhook pipelines. When full, the receivers answer `503` |
- | `oidc_accept_unverified_email` | `OIDC_ACCEPT_UNVERIFIED_EMAIL` | `false` | Accept SSO ID tokens without an `email_verified` claim (some identity providers, such as Microsoft Entra ID, never send it). An explicit `false` claim is always refused |
- | `oidc_sso_only` | `OIDC_SSO_ONLY` | `false` | Turn off ClickHouse username/password sign-in while SSO is up, also over SSO configured in the Admin page. Break-glass: `CHUI_ALLOW_PASSWORD_LOGIN=true` (env only) allows it again |
- Audit forwarding (`audit_*`), the rest of SSO (`oidc_*`) and the Pro license (`CHUI_LICENSE`, `CHUI_LICENSE_FILE`) have their own keys. The full list is in [ch-ui.com/docs/configuration](https://ch-ui.com/docs/configuration).
- ### Connector config
- ```yaml
- 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
- ```bash
- # 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](https://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`](ch-ui.conf))
- - [ ] Ensure WebSocket upgrade support for `/connect`
- - [ ] If shippers send data to CH-UI, consider a separate ingest port (`INGEST_ADDR=:4318`, `INGEST_ONLY_SEPARATE=true`) and size `INGEST_SPOOL_MAX_BYTES` for the disk
- - [ ] 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
- ```bash
- # 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
- ```bash
- 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:
- ```bash
- ch-ui server --clickhouse-url 'http://127.0.0.1:8123'
- ```
- Full guide: [ch-ui.com/docs/cant-login](https://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
- ```bash
- curl http://localhost:3488/health
- ```
- ---
- ## Development
- Requirements: Go 1.26.10+ (the version in `go.mod`), Bun
- ```bash
- 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):
- ```bash
- 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
- ```bash
- ch-ui update
- ```
- Downloads the latest release for your OS/arch, verifies checksum, and replaces the binary (on Windows, the running `.exe` too). A running server is restarted. Back up first with `ch-ui backup`; see [ch-ui.com/docs/upgrade](https://ch-ui.com/docs/upgrade).
- ---
- ## Legal
- CH-UI is dual-licensed:
- - **Community core**: [Apache 2.0](LICENSE.md). Free to use, modify, and distribute.
- - **Pro features**: [Business Source License 1.1](LICENSE.BSL) (`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`](LICENSING.md) for the authoritative scope.
- - Licensing details: [ch-ui.com/docs/license](https://ch-ui.com/docs/license)
- - Terms: [ch-ui.com/terms](https://ch-ui.com/terms)
- - Privacy: [ch-ui.com/privacy](https://ch-ui.com/privacy)
- ---
- ## Contributing
- Bug reports and pull requests are welcome. Bugs go in [issues](https://github.com/caioricciuti/ch-ui/issues/new/choose), questions in [Discussions](https://github.com/caioricciuti/ch-ui/discussions). Pull requests need a signed [Contributor License Agreement](CLA.md); a bot asks on your first one. See [CONTRIBUTING.md](CONTRIBUTING.md) for the details.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.