Installation
CH-UI ships as a single binary for server and connector operations. State lives in a local SQLite file, so there are no external services to operate.
Quick Install (Recommended)
Section titled “Quick Install (Recommended)”Download the binary for your platform from GitHub Releases:
# macOS (Apple Silicon)curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-arm64
# macOS (Intel)curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-amd64
# Linux (amd64)curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-amd64
# Linux (arm64)curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-arm64Then make it executable and install:
chmod +x ch-uisudo install -m 755 ch-ui /usr/local/bin/ch-uiOn Windows, download the .exe in PowerShell:
# Windows (x64)Invoke-WebRequest -OutFile ch-ui.exe https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-windows-amd64.exe
# Windows (ARM)Invoke-WebRequest -OutFile ch-ui.exe https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-windows-arm64.exeThe Windows binary is not code signed, so SmartScreen may warn the first time you run it. Check it against checksums.txt from the same release first:
Get-FileHash ch-ui.exe -Algorithm SHA256The hash must match the ch-ui-windows-amd64.exe (or arm64) line in checksums.txt. Then double-click ch-ui.exe, or run .\ch-ui.exe in a terminal: with no arguments on Windows it starts Desktop mode and opens your browser. Close its console window to stop it. To run a server for a team instead, use .\ch-ui.exe server.
Supported platforms:
- Linux:
amd64,arm64 - macOS:
amd64,arm64 - Windows:
amd64,arm64.ch-ui serviceis not available on Windows yet; see Desktop and CLI.
Verify Install
Section titled “Verify Install”ch-ui versionFirst Run
Section titled “First Run”# Shortcut (default command starts server)ch-ui
# Or explicit:ch-ui server --port 3488Open http://localhost:3488.
If CH-UI cannot reach ClickHouse on the first run, use the setup code printed in the server log to point it at the right URL from the login page. Find it with docker logs <container> 2>&1 | grep setup_code (Docker), journalctl -u ch-ui-server | grep setup_code (systemd) or kubectl logs deploy/<release>-ch-ui | grep setup_code (Helm). With ch-ui server --detach the log goes to ch-ui-server.log in the directory you started it from: grep setup_code ./ch-ui-server.log. See First-run setup from the login page.
Desktop (personal use)
Section titled “Desktop (personal use)”To run CH-UI just for yourself on your own computer, use ch-ui desktop:
ch-ui desktopIt differs from ch-ui server in three ways:
- It listens on
127.0.0.1only, so nobody else on your network can reach it. It refuses any address that is not loopback. - It keeps the database and the app secret key in your user data folder, not in the folder you started it from:
- macOS:
~/Library/Application Support/ch-ui - Windows:
%AppData%\ch-ui - Linux:
~/.config/ch-ui(or$XDG_CONFIG_HOME/ch-ui)
- macOS:
- It uses port 3488 when it is free and any free port otherwise, prints the URL, and opens your browser. Run it again while it is running and it only opens the browser.
The folder is created readable by you only, and the secret key file is owner-only (0600) on macOS and Linux. On Windows, %AppData% is already private to your account and the files inherit that.
Flags: --no-browser, --port (fails if that port is taken), --host (127.0.0.1, ::1 or localhost), --clickhouse-url, --connection-name. DATABASE_PATH and APP_SECRET_KEY work as they do for ch-ui server. Stop it with Ctrl+C. On Windows, ch-ui.exe with no arguments (a double-click) runs desktop; close the console window to stop it.
To share CH-UI with a team, use ch-ui server behind TLS instead. See Deployment.
Quick Start (Docker Compose)
Section titled “Quick Start (Docker Compose)”The repository’s docker-compose.yml runs CH-UI and a local ClickHouse together:
docker compose up -dOpen http://localhost:3488 and sign in with:
- Username:
admin - Password:
change-me-admin-password
That ClickHouse user is created by the compose file and has access management, so CH-UI makes it the admin. To pick your own:
CLICKHOUSE_ADMIN_USER=me CLICKHOUSE_ADMIN_PASSWORD='a-long-password' docker compose up -dThe ClickHouse container applies these every time it is recreated, so changing them and running docker compose up -d again is enough; your data is kept. If you rename the user after the first sign-in, the new name signs in as a viewer until an admin promotes it in Admin › Users. Also set APP_SECRET_KEY to a strong random value outside of a local test.
Quick Start (Docker)
Section titled “Quick Start (Docker)”Use the official GHCR image:
docker run --name ch-ui \ -p 3488:3488 \ -v ch-ui-data:/app/data \ --add-host host.docker.internal:host-gateway \ -e CLICKHOUSE_URL=http://host.docker.internal:8123 \ ghcr.io/caioricciuti/ch-ui:latestIf sign-in cannot reach ClickHouse, read the one-time setup code from the log and enter it on the login page:
docker logs ch-ui 2>&1 | grep setup_codeNotes:
CLICKHOUSE_URLis the HTTP interface, port8123(8443for HTTPS). Port9000is the native protocol and does not work.- Inside the container,
localhostis the container itself.host.docker.internalreaches the host;--add-host ... host-gatewaymakes that name work on Linux too. With Docker Compose, use the ClickHouse service name instead (http://clickhouse:8123). - Run it in the foreground the first time (no
-d) so the setup code is on screen. Detached runs keep it indocker logs. - App state is persisted at
/app/data/ch-ui.db(volume:ch-ui-data).
Local ClickHouse URL and Name (if needed)
Section titled “Local ClickHouse URL and Name (if needed)”If local login points to the wrong endpoint, restart CH-UI with explicit values:
ch-ui server --clickhouse-url http://127.0.0.1:8123 --connection-name "My Connection 1"Environment-variable equivalent:
CLICKHOUSE_URL=http://127.0.0.1:8123 CONNECTION_NAME="My Connection 1" ch-ui serverRecovery guide: Can’t login?
Manual Download (Fallback)
Section titled “Manual Download (Fallback)”If you prefer to download manually, grab the binary from GitHub Releases.
Available binaries:
ch-ui-linux-amd64ch-ui-linux-arm64ch-ui-darwin-amd64ch-ui-darwin-arm64ch-ui-windows-amd64.exech-ui-windows-arm64.exe
curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-amd64chmod +x ch-uisudo install -m 755 ch-ui /usr/local/bin/ch-uich-ui versionIf you do not install globally, run the binary directly:
./ch-ui version./ch-ui server --port 3488Local Connector Behavior
Section titled “Local Connector Behavior”When the server starts, CH-UI can run an embedded connector against local ClickHouse (http://localhost:8123) so you can get started quickly.
Recommended First Steps
Section titled “Recommended First Steps”After you sign in, Home shows a Getting started checklist. Admins see seven steps (connect ClickHouse, run a query, save a query, make a dashboard, add an AI provider, connect an AI client, invite a teammate); everyone else sees the three query and dashboard steps. Each step opens the place where it is done and ticks itself off from the real state, for example once a saved query exists. The built-in System Overview dashboard does not count. The checklist disappears when every step is done, and Hide removes it for you in this browser.
- Sign in with a ClickHouse username and password. If that fails, open Can’t login?.
- Run a first query: Home has starter queries that open in a new tab.
- Create a dashboard: New from template in Dashboards gives you a ready made one. See Dashboards.
- Configure Brain providers in Admin. See Brain.
- With a Pro license activated, open Governance and run initial sync, then check Query Insights and Cluster Health.
