Installation

CH-UI ships as a single binary for server and connector operations.

Quick Install (Recommended)

The installer script detects OS/architecture, downloads the correct release binary, verifies checksums, and installs to:

• /usr/local/bin/ch-ui when writable
• ~/.local/bin/ch-ui when non-root fallback is needed (with PATH guidance)

curl -fsSL https://ch-ui.com/install.sh | sh

Optional pinned install:

CHUI_VERSION=vX.Y.Z curl -fsSL https://ch-ui.com/install.sh | sh

Supported platforms:

• Linux: amd64, arm64
• macOS: amd64, arm64

Verify Install

ch-ui version

First Run

# Shortcut (default command starts server)
ch-ui

# Or explicit:
ch-ui server --port 3488

Open http://localhost:3488.

Quick Start (Docker)

Use the official GHCR image:

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

Notes:

• On Linux, replace host.docker.internal with a host/IP reachable from the container.
• App state is persisted at /app/data/ch-ui.db (volume: ch-ui-data).

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 server

Recovery guide: Can't login?

Manual Download (Fallback)

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

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

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

1. Login with a ClickHouse username/password.
2. If login fails, open Can't login?.
3. Configure Brain providers in Admin.
4. If Pro is enabled, open Governance and run initial sync.

Next Steps