Skip to content

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.

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

Then make it executable and install:

chmod +x ch-ui
sudo install -m 755 ch-ui /usr/local/bin/ch-ui

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

The 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 SHA256

The 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 service is not available on Windows yet; see Desktop and CLI.
ch-ui version
# Shortcut (default command starts server)
ch-ui
# Or explicit:
ch-ui server --port 3488

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

To run CH-UI just for yourself on your own computer, use ch-ui desktop:

ch-ui desktop

It differs from ch-ui server in three ways:

  • It listens on 127.0.0.1 only, 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)
  • 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.

The repository’s docker-compose.yml runs CH-UI and a local ClickHouse together:

docker compose up -d

Open 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 -d

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

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:latest

If 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_code

Notes:

  • CLICKHOUSE_URL is the HTTP interface, port 8123 (8443 for HTTPS). Port 9000 is the native protocol and does not work.
  • Inside the container, localhost is the container itself. host.docker.internal reaches the host; --add-host ... host-gateway makes 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 in docker logs.
  • App state is persisted at /app/data/ch-ui.db (volume: ch-ui-data).

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 server

Recovery guide: Can’t login?

If you prefer to download manually, grab the binary from GitHub Releases.

Available binaries:

  • ch-ui-linux-amd64
  • ch-ui-linux-arm64
  • ch-ui-darwin-amd64
  • ch-ui-darwin-arm64
  • ch-ui-windows-amd64.exe
  • ch-ui-windows-arm64.exe
curl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-amd64
chmod +x ch-ui
sudo install -m 755 ch-ui /usr/local/bin/ch-ui
ch-ui version

If you do not install globally, run the binary directly:

./ch-ui version
./ch-ui server --port 3488

When the server starts, CH-UI can run an embedded connector against local ClickHouse (http://localhost:8123) so you can get started quickly.

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.

  1. Sign in with a ClickHouse username and password. If that fails, open Can’t login?.
  2. Run a first query: Home has starter queries that open in a new tab.
  3. Create a dashboard: New from template in Dashboards gives you a ready made one. See Dashboards.
  4. Configure Brain providers in Admin. See Brain.
  5. With a Pro license activated, open Governance and run initial sync, then check Query Insights and Cluster Health.