Skip to content
Back to search

ch-ui

MarketplaceWorks with Claude CodeGitHub

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/caioricciuti--ch-ui/badge.svg)](/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)

  1. {
  2. "name": "ch-ui",
  3. "owner": { "name": "Caio Ricciuti", "url": "https://github.com/caioricciuti" },
  4. "metadata": {
  5. "description": "Plugins for CH-UI, the self-hosted ClickHouse console.",
  6. "version": "1.0.0"
  7. },
  8. "plugins": [
  9. {
  10. "name": "ch-ui",
  11. "source": "./integrations/claude-code-plugin",
  12. "description": "CH-UI MCP server connection plus a ClickHouse analytics skill.",
  13. "version": "1.0.0",
  14. "category": "database",
  15. "keywords": ["clickhouse", "sql", "analytics", "mcp"]
  16. }
  17. ]
  18. }
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)

  1. <p align="center">
  2. <img src="ui/src/assets/logo.png" alt="CH-UI Logo" width="88" />
  3. </p>
  4. <h1 align="center">CH-UI</h1>
  5. <p align="center">
  6. <strong>The open-source ClickHouse management platform.</strong><br/>
  7. SQL editor, dashboards, AI copilot, data pipelines and ingest, telemetry, models, and admin, all in one binary. Free.
  8. </p>
  9. <p align="center">
  10. <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>
  11. <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>
  12. <a href="https://github.com/caioricciuti/ch-ui/stargazers"><img src="https://img.shields.io/github/stars/caioricciuti/ch-ui" alt="Stars" /></a>
  13. <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>
  14. </p>
  15. <p align="center">
  16. <a href="https://ch-ui.com/docs"><strong>Documentation</strong></a> ·
  17. <a href="https://ch-ui.com/docs/installation">Install</a> ·
  18. <a href="https://ch-ui.com/pricing">Pricing</a> ·
  19. <a href="https://ch-ui.com/docs/changelog">Changelog</a>
  20. </p>
  21. ---
  22. ## Why CH-UI?
  23. 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**.
  24. Download one binary. Run it. Get:
  25. - A multi-tab **SQL editor** with formatting, profiling, and streaming results
  26. - **Dashboards** with a drag-and-drop panel builder and multiple chart types
  27. - **Brain**: an AI assistant that understands your schema (Anthropic, OpenAI, Ollama, or any OpenAI-compatible provider)
  28. - **Data pipelines**: visual builder for Webhook, Ingest, S3, Kafka, and DB sources into ClickHouse, with Parse, Map fields and Filter transforms
  29. - **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
  30. - **Telemetry**: search OpenTelemetry logs in ClickHouse, whether your collector writes them or CH-UI received them (traces, metrics and the service map with Pro)
  31. - **Models**: dbt-style SQL transformations with dependency graphs and scheduling
  32. - **Data lineage**: how data flows between tables, materialized views, views and dictionaries
  33. - **Admin panel**: user management, connection management, provider configuration
  34. - **Saved queries**, **schema explorer**, **connection management**, and more
  35. No Docker requirement. No external dependencies. No signup.
  36. ---
  37. ## Table of Contents
  38. - [Features (Free)](#features-free)
  39. - [Community vs Pro](#community-vs-pro)
  40. - [Quick Start](#quick-start)
  41. - [Quick Start (Docker)](#quick-start-docker)
  42. - [Architecture](#architecture)
  43. - [Remote ClickHouse (Tunnel)](#remote-clickhouse-tunnel)
  44. - [CLI Reference](#cli-reference)
  45. - [Configuration](#configuration)
  46. - [Production Checklist](#production-checklist)
  47. - [Troubleshooting](#troubleshooting)
  48. - [Development](#development)
  49. - [Upgrade](#upgrade)
  50. - [Legal](#legal)
  51. - [Contributing](#contributing)
  52. ---
  53. ## Features (Free)
  54. Everything below is included in the free Community edition under Apache 2.0.
  55. ### SQL Editor
  56. - Multi-tab interface with persistent state
  57. - CodeMirror 6 with SQL syntax highlighting and autocomplete
  58. - Query formatting and beautification
  59. - Streaming results via SSE, no timeout on long queries
  60. - **Live query progress**: elapsed time, percent complete, rows/bytes read and
  61. read throughput while the query is still running (needs `SELECT` on
  62. `system.processes`)
  63. - **Query cost estimation**: see estimated rows and parts to scan before running (like BigQuery's dry run)
  64. - Query profiling (pulls from `system.query_log`) with estimate vs actual accuracy comparison
  65. - Query plan analysis (EXPLAIN with parsed tree view)
  66. - Configurable max result rows and query timeout
  67. - Query parameters (`{name:Type}` bind params) in the editor
  68. ### Schema Explorer
  69. - Full database/table/column tree browser
  70. - Table data preview with pagination
  71. - Column type introspection
  72. - Search across databases and tables
  73. ### Dashboards
  74. - Create unlimited dashboards
  75. - Drag-and-drop panel builder
  76. - Panel types: table, stat, gauge, time series (line, area, stacked), bar, pie, histogram, scatter, heatmap and Markdown text
  77. - Drilldown links: click a value to filter the dashboard, open another dashboard, open a filled-in query, or open a URL
  78. - Time range selector with presets (1h, 24h, 7d, 30d, custom)
  79. - Timezone support
  80. - Auto-refresh control
  81. - Each panel runs its own SQL query against your ClickHouse
  82. ### Brain (AI Assistant)
  83. - Chat with your data using natural language
  84. - Multi-chat support with full history persistence
  85. - **Provider support:** Anthropic, OpenAI, OpenAI-compatible APIs (Azure, OpenRouter, Groq, Together, vLLM, etc.), Ollama (local LLMs)
  86. - Admin-controlled model and provider activation
  87. - Schema-aware context: type `@` to mention tables, dashboards, pipelines, models or saved queries in a message
  88. - SQL artifact generation: run generated queries directly from chat
  89. - Brain skills (configurable system prompts/instructions)
  90. - Global token budgets (per person, per role and dollar budgets are Pro)
  91. ### Data Pipelines
  92. - Visual pipeline canvas (drag-and-drop with XyFlow)
  93. - **Source connectors:** Webhook (inbound HTTP), Ingest (OTLP, JSON events, Elasticsearch bulk, Splunk HEC), Database (SQL query), S3, Kafka (with SCRAM auth)
  94. - **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
  95. - **Preview** on every transform node: records before and after the chain, dropped records with the reason, parse errors
  96. - **Sink:** ClickHouse, with a dead-letter table for refused rows
  97. - **Table layouts** for auto-created tables: Custom from data, Wide events (`timestamp`, `service`, `level`, `message`, `trace_id`, `attributes`), OpenTelemetry logs, OpenTelemetry traces
  98. - **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
  99. - Pipeline start/stop controls
  100. - Run history, metrics, and error tracking
  101. - Real-time monitoring (rows ingested, bytes, batches, errors, per-node counters)
  102. - Docs: [ch-ui.com/docs/pipelines](https://ch-ui.com/docs/pipelines)
  103. ### Ingest
  104. - 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)
  105. - Works with the OpenTelemetry Collector, OTel SDKs, Vector, Fluent Bit, Filebeat, Logstash, Splunk HEC clients and plain `curl`
  106. - Per-pipeline ingest keys (`chi_...`), stored hashed, shown once, revocable; per-key rate limit and per-pipeline daily quota
  107. - Requests are fsynced to a spool in `<data dir>/ingest-spool` before they are answered, then written to ClickHouse with a stable deduplication token
  108. - Logs and traces land in the OpenTelemetry exporter's table layout, so Telemetry reads them with no extra setup
  109. - **Send data here** panel in the pipeline editor fills in shipper configs with your URL and key
  110. - Optional separate listener (`--ingest-addr :4318`) for shipper traffic
  111. - Docs: [ch-ui.com/docs/ingest](https://ch-ui.com/docs/ingest/)
  112. ### Telemetry
  113. - Logs explorer over OpenTelemetry data in ClickHouse: search syntax, histograms, facets, surrounding context, logs by trace
  114. - Sources: detect the exporter's tables or map your own; saved searches
  115. - Nothing copied or indexed elsewhere, every screen is SQL against your tables
  116. - Pro: Traces, Metrics, Service map and Monitors
  117. - Docs: [ch-ui.com/docs/telemetry](https://ch-ui.com/docs/telemetry)
  118. ### Models (SQL Transformations)
  119. - dbt-style SQL models with `table`, `view`, and `incremental` materialization
  120. - Model dependency graph (DAG visualization)
  121. - Execution with dependency ordering
  122. - Run history and results tracking
  123. - Table engine configuration per model
  124. - Run manually or on a cron schedule (model and pipeline schedules are free)
  125. ### Data Lineage
  126. - See how data flows between tables, materialized views, views, dictionaries and external sources (Kafka, S3, URL, MySQL and table functions)
  127. - **Explore › Lineage** with database picker, focus search, 1 to 4 hops and kind filters; a Lineage view on every table page
  128. - Read on demand with your own ClickHouse account from system tables, cached for 30 seconds, never reads `query_log`
  129. - Docs: [ch-ui.com/docs/lineage](https://ch-ui.com/docs/lineage)
  130. ### Saved Queries
  131. - Save queries with titles and descriptions
  132. - Sort by date, name, or query length
  133. - Filter, search, copy, and organize
  134. - Quick access from the sidebar
  135. ### Admin Panel
  136. - User management (create, delete, assign roles)
  137. - ClickHouse user management (create users, update passwords, delete)
  138. - Connection management with multi-connection support
  139. - Brain provider and model configuration
  140. - Brain skill management
  141. - System statistics dashboard
  142. ### Connections & Tunnel
  143. - Multi-connection support (manage multiple ClickHouse instances)
  144. - Secure WebSocket tunnel for remote ClickHouse access
  145. - Token-based agent authentication
  146. - Connection health monitoring
  147. - Install connector as OS service (`ch-ui service install`, Linux and macOS)
  148. ### MCP Server
  149. - Embedded [Model Context Protocol](https://modelcontextprotocol.io) server at `/mcp` (streamable HTTP), in the same binary
  150. - Connect Claude Code, claude.ai, ChatGPT, Cursor or VS Code with OAuth sign-in or a revocable `chm_` key
  151. - Read tools by default: schema browsing, SELECT queries, saved queries, query plans, telemetry logs, lineage, model and pipeline status
  152. - 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
  153. - Server-side enforcement (`readonly`, row/time caps, database allowlist) + every AI call recorded in the audit log
  154. - Pro: alerts, schedules, reports, cluster health, Query Insights, Cost Center, traces and metrics tools, and running schedules and reports now
  155. - Docs: [ch-ui.com/docs/mcp](https://ch-ui.com/docs/mcp)
  156. ### Other
  157. - Dark mode
  158. - Session-based authentication with rate limiting
  159. - Security headers (CSP, X-Frame-Options, etc.)
  160. - Health check endpoint (`/health`)
  161. - Self-update (`ch-ui update`)
  162. - Personal desktop mode (`ch-ui desktop`): loopback only, data in your user folder, opens the browser
  163. - Binaries for Linux, macOS and Windows (amd64 and arm64)
  164. - Shell completion generation
  165. ---
  166. ## Community vs Pro
  167. Almost everything is free. Pro adds production operations, governance and scheduling.
  168. | Capability | Community (Free) | Pro |
  169. |---|:---:|:---:|
  170. | SQL editor + explorer + formatting + profiling | **Yes** | Yes |
  171. | Saved queries | **Yes** | Yes |
  172. | Dashboards + panel builder | **Yes** | Yes |
  173. | Brain (AI chat, multi-provider; Ask AI and agentic tools are Pro) | **Yes** | Yes |
  174. | Data pipelines (Webhook, Ingest, S3, Kafka, DB) | **Yes** | Yes |
  175. | Ingest receivers (OTLP logs and traces, JSON events, Elasticsearch bulk, Splunk HEC), ingest keys, durable spool | **Yes** | Yes |
  176. | Pipeline transforms Parse, Map fields, Filter, with preview | **Yes** | Yes |
  177. | Table layouts (Custom, Wide events, OpenTelemetry logs and traces) | **Yes** | Yes |
  178. | Models (SQL transformations, DAG, cron schedules) | **Yes** | Yes |
  179. | Admin panel + user management | **Yes** | Yes |
  180. | Multi-connection management | **Yes** | Yes |
  181. | Data lineage | **Yes** | Yes |
  182. | Desktop mode (`ch-ui desktop`) and Linux, macOS, Windows binaries | **Yes** | Yes |
  183. | Tunnel (remote ClickHouse) | **Yes** | Yes |
  184. | Query parameters in the editor (`{name:Type}` bind params) | **Yes** | Yes |
  185. | Telemetry Logs, Sources, saved searches | **Yes** | Yes |
  186. | MCP server (read tools, write tools, lifecycle actions, OAuth, API keys) | **Yes** | Yes |
  187. | Pipeline Sample, Redact and Route (up to 8 sinks per pipeline) | - | **Yes** |
  188. | Scheduled query jobs + cron + history + parameterized saved-query runs | - | **Yes** |
  189. | Scheduled reports (saved query results and dashboard summaries to email, Slack, Teams, webhooks) | - | **Yes** |
  190. | Governance (metadata catalog, access matrix, policies, incidents, query audit, audit log viewer) | - | **Yes** |
  191. | Policies + incidents + violations | - | **Yes** |
  192. | ClickHouse access control editor, access history and drift | - | **Yes** |
  193. | Access as code (export/import roles, grants, policies, quotas, profiles; create users on import) | - | **Yes** |
  194. | Guardrails (query blocking in the editor and MCP) | - | **Yes** |
  195. | Cluster Health (replication, Keeper, merges/mutations, parts pressure, long queries) | - | **Yes** |
  196. | Query Insights | - | **Yes** |
  197. | Cost Center | - | **Yes** |
  198. | Performance regressions + saved before/after investigations | - | **Yes** |
  199. | Fleet overview across connections | - | **Yes** |
  200. | Incident timeline + deployment annotations | - | **Yes** |
  201. | Schema comparison + downloadable SQL review plans | - | **Yes** |
  202. | Weekly operations reports + configured email delivery | - | **Yes** |
  203. | Alerting (SMTP, Slack, Teams, webhooks), incl. ingest and pipeline alerts | - | **Yes** |
  204. | Telemetry Traces, Metrics, Service map, Monitors | - | **Yes** |
  205. | Ask AI (text-to-SQL in the editor) + Brain agentic tools | - | **Yes** |
  206. | Brain budgets per person and per role, dollar limits | - | **Yes** |
  207. | GitHub sync for models | - | **Yes** |
  208. | SSO (OIDC) with per-person roles and attribution | - | **Yes** |
  209. | Audit forwarding to a SIEM (webhook, file, stdout) | - | **Yes** |
  210. | MCP Pro tools (operations, Query Insights, Cost Center, traces and metrics, schedule and report actions) | - | **Yes** |
  211. | Command palette Pro search (entity search, scope prefixes) | - | **Yes** |
  212. See: [ch-ui.com/docs/license](https://ch-ui.com/docs/license)
  213. Pipelines with Sample, Redact or Route nodes save on any edition; running or
  214. previewing them without Pro fails with `402` and names the node.
  215. For the performance, fleet, schema comparison and weekly report workflows, see
  216. [ch-ui.com/docs/performance](https://ch-ui.com/docs/performance).
  217. ---
  218. ## Quick Start
  219. ### 1) Download
  220. Linux (amd64):
  221. ```bash
  222. curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-amd64
  223. chmod +x ch-ui
  224. ```
  225. Linux (arm64):
  226. ```bash
  227. curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-arm64
  228. chmod +x ch-ui
  229. ```
  230. macOS (Apple Silicon):
  231. ```bash
  232. curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-arm64
  233. chmod +x ch-ui
  234. ```
  235. macOS (Intel):
  236. ```bash
  237. curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-amd64
  238. chmod +x ch-ui
  239. ```
  240. Windows (PowerShell):
  241. ```powershell
  242. # x64
  243. Invoke-WebRequest -OutFile ch-ui.exe https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-windows-amd64.exe
  244. # ARM
  245. Invoke-WebRequest -OutFile ch-ui.exe https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-windows-arm64.exe
  246. ```
  247. The Windows binary is not code signed, so SmartScreen may warn the first time
  248. you run it. Compare `Get-FileHash ch-ui.exe -Algorithm SHA256` with the
  249. matching line in `checksums.txt`.
  250. Optional: verify checksum (Linux, macOS):
  251. ```bash
  252. curl -L -o checksums.txt https://github.com/caioricciuti/ch-ui/releases/latest/download/checksums.txt
  253. sha256sum -c checksums.txt --ignore-missing
  254. ```
  255. ### 2) Run
  256. ```bash
  257. sudo install -m 755 ch-ui /usr/local/bin/ch-ui
  258. ch-ui
  259. ```
  260. Or just `./ch-ui` from the download folder.
  261. Open `http://localhost:3488` and log in with your ClickHouse credentials.
  262. On Windows, double-click `ch-ui.exe` (or run `.\ch-ui.exe`): with no arguments
  263. it starts desktop mode and opens your browser. Close its console window to stop
  264. it. Run `.\ch-ui.exe server` for a team server.
  265. ### Just for yourself: desktop mode
  266. ```bash
  267. ch-ui desktop
  268. ```
  269. Listens on `127.0.0.1` only, keeps the database and secret key in your user
  270. data folder (`~/Library/Application Support/ch-ui` on macOS,
  271. `%AppData%\ch-ui` on Windows, `$XDG_CONFIG_HOME/ch-ui` or `~/.config/ch-ui` on
  272. Linux), uses port 3488 or any free port, and opens your browser.
  273. Running it again opens the instance already running. See
  274. [ch-ui.com/docs/installation](https://ch-ui.com/docs/installation#desktop-personal-use).
  275. ---
  276. ## Quick Start (Docker)
  277. ```bash
  278. docker run --rm \
  279. -p 3488:3488 \
  280. -v ch-ui-data:/app/data \
  281. -e CLICKHOUSE_URL=http://host.docker.internal:8123 \
  282. ghcr.io/caioricciuti/ch-ui:latest
  283. ```
  284. - On Linux, replace `host.docker.internal` with a host/IP reachable from the container.
  285. - Persisted state is stored in `/app/data/ch-ui.db` (volume: `ch-ui-data`).
  286. ---
  287. ## Architecture
  288. CH-UI ships as a single binary with three operating modes:
  289. - **`server`**: web app + API + WebSocket tunnel gateway + ingest receivers (default on Linux and macOS)
  290. - **`desktop`**: the same app for one person, on `127.0.0.1` only (default on Windows)
  291. - **`connect`**: lightweight agent that exposes local ClickHouse over secure WebSocket
  292. ```mermaid
  293. flowchart LR
  294. U["Browser"] --> S["CH-UI Server\n(UI + API + Gateway)"]
  295. SH["Shippers\n(OTel, Vector, Fluent Bit, ...)"] -->|"/ingest"| S
  296. S <--> DB["SQLite + ingest spool\n(state, settings, chats, dashboards)"]
  297. A["ch-ui connect\n(Agent)"] <--> S
  298. A --> CH["ClickHouse"]
  299. ```
  300. For local use, the server starts an embedded connector automatically against `localhost:8123`.
  301. **Tech stack:** Go backend (chi v5, SQLite WAL mode), Svelte 5 frontend (TypeScript, Vite, TailwindCSS), embedded at build time.
  302. ---
  303. ## Remote ClickHouse (Tunnel)
  304. Connect to ClickHouse instances running on other machines using the secure WebSocket tunnel.
  305. **Server (VM2):**
  306. ```bash
  307. ch-ui server --port 3488
  308. ```
  309. **Agent (VM1, where ClickHouse runs):**
  310. ```bash
  311. ch-ui connect --url wss://your-ch-ui-domain/connect --key cht_your_tunnel_token
  312. ```
  313. ### Tunnel key management
  314. Run these on the server host:
  315. ```bash
  316. ch-ui tunnel create --name "vm1-clickhouse" # Create connection + key
  317. ch-ui tunnel list # List all connections
  318. ch-ui tunnel show <connection-id> # Show token + setup commands
  319. ch-ui tunnel rotate <connection-id> # Rotate token (old one invalidated)
  320. ch-ui tunnel delete <connection-id> # Delete connection
  321. ```
  322. - Token can also be generated from the Admin UI.
  323. - Agent only needs outbound access to the server's `/connect` endpoint.
  324. - Add `--takeover` to replace a stale agent session.
  325. - Install as OS service: `ch-ui service install --key cht_xxx --url wss://host/connect`
  326. For full hardening guide: [ch-ui.com/docs/deployment](https://ch-ui.com/docs/deployment)
  327. ---
  328. ## CLI Reference
  329. ### Quick start commands
  330. ```bash
  331. ch-ui # Start server (local ClickHouse); desktop mode on Windows
  332. ch-ui desktop # Run for yourself on 127.0.0.1 and open the browser
  333. ch-ui server start --detach # Start in background
  334. ch-ui server status # Check if running
  335. ch-ui server stop # Stop server
  336. ```
  337. ### Full command map
  338. | Command | Description |
  339. |---|---|
  340. | `ch-ui` / `ch-ui server` | Start web app + API + gateway + ingest receivers (`ch-ui` alone runs `desktop` on Windows) |
  341. | `ch-ui desktop` | Run CH-UI for yourself on this computer, loopback only, and open the browser |
  342. | `ch-ui connect` | Start tunnel agent next to ClickHouse |
  343. | `ch-ui tunnel create/list/show/rotate/delete` | Manage tunnel keys (server host) |
  344. | `ch-ui server start/stop/status/restart` | Run the server in the background and manage it through its PID file |
  345. | `ch-ui service install/start/stop/restart/status/logs/uninstall` | Manage connector as OS service (Linux and macOS; not supported on Windows yet) |
  346. | `ch-ui backup [file]` | Consistent snapshot of the SQLite database |
  347. | `ch-ui reset-admin [--user <name>] [--connection <id-or-name>]` | Recover the CH-UI admin role when no admin can sign in |
  348. | `ch-ui update` | Update to latest release (restarts a running server; `--pid-file`, `--stop-timeout`, `--restart-server`) |
  349. | `ch-ui version` | Print version |
  350. | `ch-ui completion bash/zsh/fish/powershell` | Generate shell completions |
  351. | `ch-ui uninstall` | Remove CH-UI from system (stops a running `desktop`, keeps its data folder; `--print-only` to preview) |
  352. ### Server flags
  353. | Flag | Default | Description |
  354. |---|---|---|
  355. | `--port, -p` | `3488` | HTTP port |
  356. | `--clickhouse-url` | `http://localhost:8123` | Local ClickHouse URL |
  357. | `--connection-name` | `Local ClickHouse` | Display name for local connection |
  358. | `--config, -c` | - | Path to `server.yaml` |
  359. | `--detach` | - | Run in background |
  360. | `--dev` | - | Development mode (proxy to Vite) |
  361. | `--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 |
  362. | `--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 |
  363. | `--ingest-addr` | off | Also serve the `/ingest` receivers (and `/v1` OTLP aliases) on this address, e.g. `:4318` |
  364. | `--pid-file` | `ch-ui-server.pid` | Path to server PID file |
  365. | `--stop-timeout` | `10s` | Graceful stop timeout |
  366. `ch-ui server restart` runs in the background by default (`--detach=false` to
  367. stay in the foreground).
  368. ### Desktop flags
  369. | Flag | Default | Description |
  370. |---|---|---|
  371. | `--port, -p` | `3488` | Port; if the default is taken, any free port is used. An explicit port fails when taken |
  372. | `--host` | `127.0.0.1` | Loopback address (`127.0.0.1`, `::1` or `localhost`) |
  373. | `--no-browser` | - | Do not open the browser |
  374. | `--clickhouse-url` | `http://localhost:8123` | Local ClickHouse URL |
  375. | `--connection-name` | `Local ClickHouse` | Display name for local connection |
  376. | `--config, -c` | - | Path to `server.yaml` |
  377. `DATABASE_PATH` and `APP_SECRET_KEY` override the database and key as they do
  378. for `ch-ui server`.
  379. ### Connect flags
  380. | Flag | Default | Description |
  381. |---|---|---|
  382. | `--url` | `ws://127.0.0.1:3488/connect` | WebSocket tunnel URL (`ws://` or `wss://`); falls back to `TUNNEL_URL`, then the config file |
  383. | `--key` | - | Tunnel token (`cht_...`) |
  384. | `--clickhouse-url` | `http://localhost:8123` | Local ClickHouse |
  385. | `--config, -c` | - | Path to `config.yaml` |
  386. | `--detach` | - | Run in background |
  387. | `--takeover` | - | Replace stale agent session |
  388. ---
  389. ## Configuration
  390. CH-UI works without config files. You only need them for production defaults or service-managed startup.
  391. ### Config file locations
  392. | File | macOS | Linux | Windows |
  393. |---|---|---|---|
  394. | `server.yaml` | `~/.config/ch-ui/server.yaml` | `/etc/ch-ui/server.yaml` | pass `--config` |
  395. | `config.yaml` | `~/.config/ch-ui/config.yaml` | `/etc/ch-ui/config.yaml` | `%AppData%\ch-ui\connect\config.yaml` |
  396. **Priority:** CLI flags > environment variables > config file > built-in defaults
  397. ### Server config
  398. ```yaml
  399. port: 3488
  400. app_url: https://ch-ui.yourcompany.com
  401. database_path: /var/lib/ch-ui/ch-ui.db
  402. clickhouse_url: http://localhost:8123
  403. connection_name: Local ClickHouse
  404. app_secret_key: "change-this-in-production"
  405. allowed_origins:
  406. - https://ch-ui.yourcompany.com
  407. ```
  408. | Key | Env var | Default | Description |
  409. |---|---|---|---|
  410. | `port` | `PORT` | `3488` | HTTP port |
  411. | `app_url` | `APP_URL` | `http://localhost:<port>` | Public URL for links and tunnel inference |
  412. | `database_path` | `DATABASE_PATH` | `./data/ch-ui.db` | SQLite database location |
  413. | `clickhouse_url` | `CLICKHOUSE_URL` | `http://localhost:8123` | Embedded local connection target |
  414. | `connection_name` | `CONNECTION_NAME` | `Local ClickHouse` | Display name for local connection |
  415. | `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 |
  416. | `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 |
  417. | `allowed_origins` | `ALLOWED_ORIGINS` | empty | CORS allowlist (comma-separated in env) |
  418. | `tunnel_url` | `TUNNEL_URL` | derived from port | Tunnel endpoint advertised to agents |
  419. | `session_max_age` | `SESSION_MAX_AGE` | `604800` (7 days) | Session lifetime in seconds |
  420. | `allow_login_url` | `ALLOW_LOGIN_URL` | `false` | Same as `--allow-login-url` |
  421. | `trusted_proxies` | `TRUSTED_PROXIES` | loopback, private and link-local ranges | Same as `--trusted-proxies` (list in YAML, comma-separated in env) |
  422. | `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 |
  423. | `export_max_bytes` / `export_max_rows` | `EXPORT_MAX_BYTES` / `EXPORT_MAX_ROWS` | 1 GiB / 10,000,000 | Caps on one full result export |
  424. | `ingest_addr` | `INGEST_ADDR` | off | Same as `--ingest-addr` |
  425. | `ingest_only_separate` | `INGEST_ONLY_SEPARATE` | `false` | With `ingest_addr` set, stop serving `/ingest` on the main port |
  426. | `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` |
  427. | `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 |
  428. | `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 |
  429. 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).
  430. ### Connector config
  431. ```yaml
  432. tunnel_token: "cht_your_token"
  433. clickhouse_url: "http://127.0.0.1:8123"
  434. tunnel_url: "wss://your-ch-ui-domain/connect"
  435. ```
  436. | Key | Env var | Default | Description |
  437. |---|---|---|---|
  438. | `tunnel_token` | `TUNNEL_TOKEN` | required | Auth key from `ch-ui tunnel create` |
  439. | `clickhouse_url` | `CLICKHOUSE_URL` | `http://localhost:8123` | Local ClickHouse |
  440. | `tunnel_url` | `TUNNEL_URL` | `ws://127.0.0.1:3488/connect` | Server gateway endpoint |
  441. ### Changing the local ClickHouse URL
  442. ```bash
  443. # CLI flag
  444. ch-ui server --clickhouse-url http://127.0.0.1:8123
  445. # Environment variable
  446. CLICKHOUSE_URL=http://127.0.0.1:8123 ch-ui server
  447. # With custom connection name
  448. ch-ui server --clickhouse-url http://127.0.0.1:8123 --connection-name "My ClickHouse"
  449. ```
  450. The login page also has a **Can't login?** button that shows setup guidance.
  451. CH-UI can connect to ClickHouse either directly (point `CLICKHOUSE_URL` at the
  452. endpoint, including a reverse-proxied `https://` one) or via an outbound tunnel
  453. that keeps ClickHouse fully private. See
  454. [ch-ui.com/docs/connections](https://ch-ui.com/docs/connections).
  455. ---
  456. ## Production Checklist
  457. - [ ] Set a strong `APP_SECRET_KEY`
  458. - [ ] Set `APP_URL` to your public HTTPS URL
  459. - [ ] Configure `ALLOWED_ORIGINS`
  460. - [ ] Put CH-UI behind a TLS reverse proxy (Nginx example: [`ch-ui.conf`](ch-ui.conf))
  461. - [ ] Ensure WebSocket upgrade support for `/connect`
  462. - [ ] 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
  463. - [ ] Back up the SQLite database regularly with `ch-ui backup`, and keep `APP_SECRET_KEY` safe
  464. - [ ] Run connector as OS service on remote hosts
  465. ### Backup and restore
  466. ```bash
  467. # Backup: consistent snapshot, safe while the server is running
  468. ch-ui backup /var/backups/ch-ui-$(date +%F).db -c /etc/ch-ui/server.yaml
  469. # Restore: stop the server, replace the DB file with the backup, start it
  470. # again with the same APP_SECRET_KEY
  471. ```
  472. Do not `cp` the live database: it runs in WAL mode and a plain copy can be
  473. inconsistent. The backup holds credentials encrypted with `APP_SECRET_KEY`, so
  474. back up that key too (or the `.app_secret_key` file next to the database when
  475. the key was auto-generated). A backup is useless without it.
  476. ---
  477. ## Troubleshooting
  478. ### Port already in use
  479. ```bash
  480. ch-ui server status # Check if already running
  481. ch-ui server stop # Stop the old process
  482. ```
  483. ### Can't log in
  484. - **Authentication failed**: wrong ClickHouse credentials
  485. - **Connection unavailable**: wrong URL or connector offline
  486. - **Too many attempts**: wait for retry window; fix URL first if needed
  487. Click **Can't login?** on the login page for guided recovery, or restart with:
  488. ```bash
  489. ch-ui server --clickhouse-url 'http://127.0.0.1:8123'
  490. ```
  491. Full guide: [ch-ui.com/docs/cant-login](https://ch-ui.com/docs/cant-login)
  492. ### Connector auth fails (`invalid token`)
  493. - Verify you copied the latest `cht_...` token
  494. - Check with `ch-ui tunnel list`
  495. - Rotate with `ch-ui tunnel rotate <connection-id>`
  496. ### WebSocket fails behind proxy
  497. Your proxy must forward upgrades on `/connect`:
  498. - `Upgrade` and `Connection: upgrade` headers
  499. - Long read/send timeouts
  500. - Buffering disabled for tunnel path
  501. ### Health check
  502. ```bash
  503. curl http://localhost:3488/health
  504. ```
  505. ---
  506. ## Development
  507. Requirements: Go 1.26.10+ (the version in `go.mod`), Bun
  508. ```bash
  509. git clone https://github.com/caioricciuti/ch-ui.git
  510. cd ch-ui
  511. make build # Full production build (frontend + Go binary)
  512. ./ch-ui
  513. ```
  514. Dev mode (two terminals):
  515. ```bash
  516. make dev # Terminal 1: Go server
  517. cd ui && bun install && bun run dev # Terminal 2: Vite dev server
  518. ```
  519. Useful targets: `make build` | `make test` | `make vet` | `make clean` | `make rebuild`
  520. ---
  521. ## Upgrade
  522. ```bash
  523. ch-ui update
  524. ```
  525. 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).
  526. ---
  527. ## Legal
  528. CH-UI is dual-licensed:
  529. - **Community core**: [Apache 2.0](LICENSE.md). Free to use, modify, and distribute.
  530. - **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.
  531. - Licensing details: [ch-ui.com/docs/license](https://ch-ui.com/docs/license)
  532. - Terms: [ch-ui.com/terms](https://ch-ui.com/terms)
  533. - Privacy: [ch-ui.com/privacy](https://ch-ui.com/privacy)
  534. ---
  535. ## Contributing
  536. 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 in

Free to use. If it’s helped, pass it on.