{"id":17570629,"url":"https://github.com/caioricciuti/ch-ui","last_synced_at":"2026-02-24T23:10:25.714Z","repository":{"id":240117085,"uuid":"801710502","full_name":"caioricciuti/ch-ui","owner":"caioricciuti","description":"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.","archived":false,"fork":false,"pushed_at":"2026-02-20T22:34:01.000Z","size":37777,"stargazers_count":593,"open_issues_count":6,"forks_count":57,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-21T01:10:29.617Z","etag":null,"topics":["big-data","big-data-analytics","big-data-visualization","clickhouse-ui"],"latest_commit_sha":null,"homepage":"https://ch-ui.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caioricciuti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-05-16T19:04:08.000Z","updated_at":"2026-02-20T21:55:43.000Z","dependencies_parsed_at":"2024-06-01T17:34:37.821Z","dependency_job_id":"b1df042b-9ab6-4cb2-a904-025206ad09b7","html_url":"https://github.com/caioricciuti/ch-ui","commit_stats":null,"previous_names":["caioricciuti/ch-ui"],"tags_count":72,"template":false,"template_full_name":null,"purl":"pkg:github/caioricciuti/ch-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caioricciuti%2Fch-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caioricciuti%2Fch-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caioricciuti%2Fch-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caioricciuti%2Fch-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caioricciuti","download_url":"https://codeload.github.com/caioricciuti/ch-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caioricciuti%2Fch-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29727736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T20:09:16.275Z","status":"ssl_error","status_checked_at":"2026-02-22T20:09:13.750Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["big-data","big-data-analytics","big-data-visualization","clickhouse-ui"],"created_at":"2024-10-21T18:01:15.735Z","updated_at":"2026-02-24T23:10:25.708Z","avatar_url":"https://github.com/caioricciuti.png","language":"Go","funding_links":[],"categories":["UIs","Go"],"sub_categories":["GUI"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"ui/src/assets/logo.png\" alt=\"CH-UI Logo\" width=\"88\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eCH-UI\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  ClickHouse workspace for teams that ship fast.\u003cbr/\u003e\n  Querying, governance, AI copilot, scheduling, and operations in one binary.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/caioricciuti/ch-ui/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/caioricciuti/ch-ui?label=version\" alt=\"Version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/caioricciuti/ch-ui/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/caioricciuti/ch-ui/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/caioricciuti/ch-ui\" alt=\"Stars\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Table Of Contents\n\n- [What Is CH-UI?](#what-is-ch-ui)\n- [Why Teams Use CH-UI](#why-teams-use-ch-ui)\n- [Architecture](#architecture)\n- [Feature Overview](#feature-overview)\n- [Quick Start (Local)](#quick-start-local)\n- [Quick Start (Docker)](#quick-start-docker)\n- [Change Local ClickHouse URL](#change-local-clickhouse-url)\n- [Can't Login?](#cant-login)\n- [Remote ClickHouse (VM2 Server + VM1 Agent)](#remote-clickhouse-vm2-server--vm1-agent)\n- [Tunnel Key Management (Server Host)](#tunnel-key-management-server-host)\n- [CLI Reference](#cli-reference)\n- [Configuration](#configuration)\n- [Production Checklist](#production-checklist)\n- [Governance, Brain, and Alerts](#governance-brain-and-alerts)\n- [Troubleshooting](#troubleshooting)\n- [Development](#development)\n- [Upgrade](#upgrade)\n- [Legal](#legal)\n- [Contributing](#contributing)\n\n---\n\n## What Is CH-UI?\n\nCH-UI is a self-hosted ClickHouse control plane that runs as a single executable.\n\nIt includes:\n- A multi-tab SQL editor and explorer\n- Dashboards and scheduled jobs\n- Governance and access visibility\n- Brain (AI assistant with chat history and artifacts)\n- Admin workflows for users, providers, alerts, and operations\n\nNo Docker requirement. No extra backend services required to start.\n\n---\n\n## Why Teams Use CH-UI\n\n- Fast setup: download binary, run, open browser\n- Real operations: status, restart/stop, connector lifecycle, sync visibility\n- Production flow: tunnel architecture for remote ClickHouse\n- Governance value: lineage, incidents, policies, access matrix\n- AI that is practical: model/provider control, persisted chats, SQL-aware artifacts\n\n---\n\n## Architecture\n\nCH-UI supports two operating modes from the same binary:\n- `server`: web app + API + tunnel gateway\n- `connect`: lightweight agent that exposes local ClickHouse over secure WebSocket\n\n```mermaid\nflowchart LR\n    U[\"Browser\"] --\u003e S[\"CH-UI Server\\n(UI + API + Gateway)\"]\n    S \u003c--\u003e DB[\"SQLite\\n(state, settings, chats, governance cache)\"]\n    A[\"ch-ui connect (Agent)\"] \u003c--\u003e S\n    A --\u003e CH[\"ClickHouse\"]\n```\n\nFor local development, the server starts an embedded connector automatically (localhost ClickHouse).\n\n---\n\n## Feature Overview\n\n### Community (Apache 2.0)\n- SQL editor + result views\n- Database/table explorer\n- Saved queries\n- Local-first single-binary runtime\n\n### Pro (license required)\n- Dashboards and panel builder\n- Schedules and execution history\n- Brain (multi-chat, model/provider management, artifacts)\n- Governance (metadata, access, incidents, policies, lineage)\n- Admin panel and multi-connection operations\n- Alerts (SMTP, Resend, Brevo) for policy/schedule/governance events\n\nSee: [`docs/license.md`](docs/license.md)\n\n---\n\n## Community vs Pro\n\n| Capability | Community | Pro |\n|---|:---:|:---:|\n| SQL editor + explorer | Yes | Yes |\n| Saved queries | Yes | Yes |\n| Dashboards | - | Yes |\n| Schedules | - | Yes |\n| Brain (AI) | - | Yes |\n| Governance + incidents + policies | - | Yes |\n| Alerting channels/rules | - | Yes |\n| Multi-connection admin workflows | - | Yes |\n\n---\n\n## Quick Start (Local)\n\n### 1) Download\n\nLinux (amd64):\n```bash\ncurl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-amd64\nchmod +x ch-ui\n```\n\nLinux (arm64):\n```bash\ncurl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-linux-arm64\nchmod +x ch-ui\n```\n\nmacOS (Apple Silicon):\n```bash\ncurl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-arm64\nchmod +x ch-ui\n```\n\nmacOS (Intel):\n```bash\ncurl -L -o ch-ui https://github.com/caioricciuti/ch-ui/releases/latest/download/ch-ui-darwin-amd64\nchmod +x ch-ui\n```\n\n### Optional: verify checksum\n\n```bash\ncurl -L -o checksums.txt https://github.com/caioricciuti/ch-ui/releases/latest/download/checksums.txt\nsha256sum -c checksums.txt --ignore-missing\n```\n\n### 2) Start server\n\nInstall globally and run with `ch-ui`:\n\n```bash\nsudo install -m 755 ch-ui /usr/local/bin/ch-ui\nch-ui\n```\n\nIf you prefer not to install globally, run `./ch-ui` from the download folder.\n\nDefault address: `http://localhost:3488`\n\n### 3) Log in\n\nUse a ClickHouse user/password for the selected connection.\nFor local setup, CH-UI uses the embedded connector against `http://localhost:8123` by default.\n\n---\n\n## Quick Start (Docker)\n\nRun the official image:\n\n```bash\ndocker run --rm \\\n  -p 3488:3488 \\\n  -v ch-ui-data:/app/data \\\n  -e CLICKHOUSE_URL=http://host.docker.internal:8123 \\\n  ghcr.io/caioricciuti/ch-ui:latest\n```\n\nNotes:\n- On Linux, replace `host.docker.internal` with a host/IP reachable from the container.\n- Persisted state is stored in `/app/data/ch-ui.db` (volume: `ch-ui-data`).\n\n---\n\n## Change Local ClickHouse URL\n\nIf `Local ClickHouse` points to the wrong endpoint, restart CH-UI with one of the options below:\n\nCLI flag:\n```bash\nch-ui server --clickhouse-url http://127.0.0.1:8123\n```\n\nEnvironment variable:\n```bash\nCLICKHOUSE_URL=http://127.0.0.1:8123 ch-ui server\n```\n\nSet a custom local connection name (optional):\n```bash\nch-ui server --clickhouse-url http://127.0.0.1:8123 --connection-name \"My Connection 1\"\n```\n\nEnvironment variable equivalent:\n```bash\nCLICKHOUSE_URL=http://127.0.0.1:8123 CONNECTION_NAME=\"My Connection 1\" ch-ui server\n```\n\nConfig file (`server.yaml`):\n```yaml\nclickhouse_url: http://127.0.0.1:8123\nconnection_name: My Connection 1\n```\n\nThen start with:\n```bash\nch-ui server -c /etc/ch-ui/server.yaml\n```\n\nPriority order for this setting:\n- CLI flag (`--clickhouse-url`)\n- Environment variable (`CLICKHOUSE_URL`)\n- Config file (`server.yaml`)\n- Built-in default (`http://localhost:8123`)\n\nConnection display name priority:\n- CLI flag (`--connection-name`)\n- Environment variable (`CONNECTION_NAME`)\n- Config file (`connection_name`)\n- Built-in default (`Local ClickHouse`)\n\nTip: The login page includes a **Can't login?** action that opens a setup sheet (URL + connection name only; credentials stay in Sign in).\nChanging this local URL does not require Admin access (Admin and multi-connection management are Pro-only).\n\n---\n\n## Can't login?\n\nUse this path when login fails and you need fast recovery from the login screen.\n\n1. In login, click **Can't login?**.\n2. Set `ClickHouse URL` and `Connection Name`.\n3. Restart CH-UI with one command:\n\n```bash\nch-ui server --clickhouse-url 'http://127.0.0.1:8123' --connection-name 'My Connection 1'\n```\n\nOr local binary:\n\n```bash\n./ch-ui server --clickhouse-url 'http://127.0.0.1:8123' --connection-name 'My Connection 1'\n```\n\nDocker:\n\n```bash\ndocker run --rm -p 3488:3488 -v ch-ui-data:/app/data \\\n  -e CLICKHOUSE_URL='http://127.0.0.1:8123' \\\n  -e CONNECTION_NAME='My Connection 1' \\\n  ghcr.io/caioricciuti/ch-ui:latest\n```\n\nQuick diagnosis:\n- `Authentication failed`: wrong credentials for selected connection.\n- `Connection unavailable` / `Unreachable`: wrong local URL or connector offline.\n- `Too many login attempts`: wait retry window; if URL was wrong, fix setup and restart first.\n\nFull guide: [`docs/cant-login.md`](docs/cant-login.md)\n\n---\n\n## Remote ClickHouse (VM2 Server + VM1 Agent)\n\nThis is the recommended production topology:\n- VM2: `ch-ui server`\n- VM1 (where ClickHouse runs): `ch-ui connect`\n\n### VM2: start CH-UI server\n```bash\nch-ui server --port 3488\n```\n\n### VM1: connect agent to VM2\n```bash\nch-ui connect --url wss://your-ch-ui-domain/connect --key cht_your_tunnel_token\n```\n\nNotes:\n- Token can be generated in UI or via `ch-ui tunnel create` on the server host.\n- VM1 only needs outbound access to VM2 `/connect`.\n- If a stale session exists, add `--takeover`.\n\nFor full hardening guide: [`docs/production-runbook.md`](docs/production-runbook.md)\n\n---\n\n## Tunnel Key Management (Server Host)\n\nRun these on the CH-UI server host (VM where `ch-ui.db` lives):\n\n```bash\n# Create a connection + key\nch-ui tunnel create --name \"vm1-clickhouse\"\n\n# List all tunnel connections\nch-ui tunnel list\n\n# Show full token + setup commands for one connection\nch-ui tunnel show \u003cconnection-id\u003e\n\n# Rotate token (old token becomes invalid immediately)\nch-ui tunnel rotate \u003cconnection-id\u003e\n\n# Delete a tunnel connection\nch-ui tunnel delete \u003cconnection-id\u003e\n```\n\nUseful flags:\n- `--config, -c` use a specific server config file\n- `--db` override SQLite path directly\n- `--url` force public websocket URL used in generated setup commands\n\n---\n\n## CLI Reference\n\n### If you are new, run these first\n\nLocal machine (fastest way):\n```bash\nch-ui\n```\n\nRemote setup (VM2 server + VM1 ClickHouse):\n```bash\n# VM2\nch-ui server start --detach\nch-ui tunnel create --name \"vm1-clickhouse\" --url wss://your-domain/connect\n\n# VM1\nch-ui connect --url wss://your-domain/connect --key cht_xxx --clickhouse-url http://127.0.0.1:8123\n```\n\n### Full command map\n\nTop-level commands:\n```bash\nch-ui\nch-ui server\nch-ui connect\nch-ui tunnel\nch-ui service\nch-ui update\nch-ui version\nch-ui completion\nch-ui help\n```\n\n### `server` (run CH-UI web app/API/gateway)\n\n```bash\nch-ui server\nch-ui server start --detach\nch-ui server status\nch-ui server stop\nch-ui server restart\n```\n\nCommon flags:\n- `--port, -p` HTTP port (default `3488`)\n- `--clickhouse-url` Local ClickHouse HTTP URL for embedded connection (default `http://localhost:8123`)\n- `--connection-name` Display name for embedded local connection (default `Local ClickHouse`)\n- `--config, -c` path to `server.yaml`\n- `--detach` run in background\n- `--pid-file` PID file location\n- `--stop-timeout` graceful stop timeout\n- `--dev` development mode (frontend proxy)\n\n### `connect` (agent next to ClickHouse)\n\n```bash\nch-ui connect --url wss://host/connect --key cht_xxx --clickhouse-url http://127.0.0.1:8123\nch-ui connect --detach\nch-ui connect --takeover\n```\n\nCommon flags:\n- `--url` WebSocket tunnel URL (`ws://` or `wss://`)\n- `--key` tunnel token (`cht_...`)\n- `--clickhouse-url` ClickHouse HTTP endpoint\n- `--config, -c` connector config file path\n- `--detach` run in background\n- `--takeover` replace currently connected agent for same token\n\n### `tunnel` (create/manage keys on server host)\n\n```bash\nch-ui tunnel create --name \"vm1-clickhouse\"\nch-ui tunnel list\nch-ui tunnel show \u003cconnection-id\u003e\nch-ui tunnel rotate \u003cconnection-id\u003e\nch-ui tunnel delete \u003cconnection-id\u003e\n```\n\nCommon flags:\n- `--config, -c` path to `server.yaml`\n- `--db` override SQLite database path\n- `--url` public URL used when printing connect/service setup commands\n\n### `service` (install connector as OS service)\n\n```bash\nch-ui service install --key cht_xxx --url wss://host/connect --clickhouse-url http://127.0.0.1:8123\nch-ui service status\nch-ui service start\nch-ui service stop\nch-ui service restart\nch-ui service logs -f\nch-ui service uninstall\n```\n\n### Other commands\n\n```bash\nch-ui uninstall         # best-effort local uninstall + manual cleanup commands\nch-ui update            # update binary to latest release\nch-ui version           # print version\nch-ui completion bash   # generate shell completion\nch-ui help              # show help\n```\n\n---\n\n## Configuration\n\nGood news: CH-UI works without config files.\n\nYou only need config files when:\n- you want production defaults\n- you want service-managed startup\n- you want to avoid passing flags every time\n\n### Where config files live\n\n- Server config (`server.yaml`)\n- macOS: `~/.config/ch-ui/server.yaml`\n- Linux: `/etc/ch-ui/server.yaml`\n\n- Connector config (`config.yaml`)\n- macOS: `~/.config/ch-ui/config.yaml`\n- Linux: `/etc/ch-ui/config.yaml`\n\n### How values are chosen (priority)\n\nServer:\n- CLI flags \u003e environment variables \u003e `server.yaml` \u003e built-in defaults\n\nConnector:\n- CLI flags \u003e environment variables \u003e `config.yaml` \u003e built-in defaults\n\n### Server config (`server.yaml`) explained\n\n```yaml\nport: 3488\napp_url: https://ch-ui.yourcompany.com\ndatabase_path: /var/lib/ch-ui/ch-ui.db\nclickhouse_url: http://localhost:8123\nconnection_name: Local ClickHouse\napp_secret_key: \"change-this-in-production\"\nallowed_origins:\n  - https://ch-ui.yourcompany.com\n# optional override:\n# tunnel_url: wss://ch-ui.yourcompany.com/connect\n```\n\nWhat each key means:\n\n| Key | Example | Default | Why it matters |\n|---|---|---|---|\n| `port` | `3488` | `3488` | HTTP port used by CH-UI server |\n| `app_url` | `https://ch-ui.example.com` | `http://localhost:\u003cport\u003e` | Public URL for links and tunnel URL inference |\n| `database_path` | `/var/lib/ch-ui/ch-ui.db` | `./data/ch-ui.db` | Where CH-UI stores app state |\n| `clickhouse_url` | `http://localhost:8123` | `http://localhost:8123` | Embedded local connection target |\n| `connection_name` | `My Connection 1` | `Local ClickHouse` | Display name shown in login/session for embedded local connection |\n| `app_secret_key` | random long string | auto-generated per install (persisted at `\u003cdatabase_dir\u003e/.app_secret_key`) | Encrypts session credentials; set explicitly in production |\n| `allowed_origins` | `[\"https://ch-ui.example.com\"]` | empty | CORS allowlist |\n| `tunnel_url` | `wss://ch-ui.example.com/connect` | derived from port | Explicit tunnel endpoint advertised to agents |\n\nServer environment variables:\n- `PORT`\n- `APP_URL`\n- `DATABASE_PATH`\n- `CLICKHOUSE_URL`\n- `CONNECTION_NAME`\n- `APP_SECRET_KEY`\n- `ALLOWED_ORIGINS` (comma-separated)\n- `TUNNEL_URL`\n\nIf `APP_SECRET_KEY` is not configured, CH-UI generates a strong local key and persists it next to the database path as `.app_secret_key`.\n\n### Connector config (`config.yaml`) explained\n\n```yaml\ntunnel_token: \"cht_your_token\"\nclickhouse_url: \"http://127.0.0.1:8123\"\ntunnel_url: \"wss://your-ch-ui-domain/connect\"\n# insecure_skip_verify: false\n```\n\nWhat each key means:\n\n| Key | Example | Default | Why it matters |\n|---|---|---|---|\n| `tunnel_token` | `cht_...` | none (required) | Auth key created on server (`ch-ui tunnel create`) |\n| `clickhouse_url` | `http://127.0.0.1:8123` | `http://localhost:8123` | Local ClickHouse for this VM |\n| `tunnel_url` | `wss://ch-ui.example.com/connect` | `ws://127.0.0.1:3488/connect` | Server gateway endpoint |\n| `insecure_skip_verify` | `false` | `false` | Only for insecure dev TLS setups |\n\nConnector environment variables:\n- `TUNNEL_TOKEN`\n- `CLICKHOUSE_URL`\n- `TUNNEL_URL`\n- `TUNNEL_INSECURE_SKIP_VERIFY`\n\n### Minimal production templates (copy/paste)\n\nServer (`/etc/ch-ui/server.yaml`):\n```yaml\nport: 3488\napp_url: https://ch-ui.example.com\ndatabase_path: /var/lib/ch-ui/ch-ui.db\napp_secret_key: \"replace-with-a-long-random-secret\"\nallowed_origins:\n  - https://ch-ui.example.com\n```\n\nConnector (`/etc/ch-ui/config.yaml`):\n```yaml\ntunnel_token: \"cht_replace_me\"\nclickhouse_url: \"http://127.0.0.1:8123\"\ntunnel_url: \"wss://ch-ui.example.com/connect\"\n```\n\n---\n\n## Production Checklist\n\n- Set a strong `APP_SECRET_KEY`\n- Set `APP_URL` to your public HTTPS URL\n- Configure `ALLOWED_ORIGINS`\n- Put CH-UI behind TLS reverse proxy\n- Ensure WebSocket upgrade support for `/connect`\n- Back up SQLite database (`database_path`)\n- Run connector as service on remote hosts\n\nNginx example is included: [`ch-ui.conf`](ch-ui.conf)\n\n### Backup and restore\n\nCH-UI state is stored in SQLite (`database_path`), so backup is simple:\n\n```bash\ncp /var/lib/ch-ui/ch-ui.db /var/backups/ch-ui-$(date +%F).db\n```\n\nRestore by replacing the DB file while server is stopped.\n\n---\n\n## Governance, Brain, and Alerts\n\n### Governance\n- Metadata sync (databases/tables/columns)\n- Query log + lineage ingestion\n- Access sync (users/roles/grants/matrix)\n- Policies and incidents workflow\n\n### Brain\n- Multiple chats per user/connection\n- Provider layer (OpenAI, OpenAI-compatible, Ollama)\n- Admin-controlled provider/model activation and defaults\n- Artifacts persisted in database\n\n### Alerts\n- Channel providers: SMTP, Resend, Brevo\n- Rules by event type/severity\n- Route-level delivery and escalation options\n\n---\n\n## Troubleshooting\n\n### `listen tcp :3488: bind: address already in use`\nAnother process is already using the port.\n\nCheck:\n```bash\nch-ui server status\n```\nThen stop old process:\n```bash\nch-ui server stop\n```\n\nIf status says PID file is missing but port is in use, you likely upgraded from an older binary without PID management. Stop the old process once, then restart with current build.\n\n### Connector keeps failing auth (`invalid token`)\n- Verify you copied the latest `cht_...` token\n- Check active connections with `ch-ui tunnel list`\n- Regenerate with `ch-ui tunnel rotate \u003cconnection-id\u003e` (or create a new one with `ch-ui tunnel create --name ...`)\n- Confirm agent uses correct `--url` and token pair\n\n### Login fails but no clarity\nCH-UI now surfaces explicit login states (invalid credentials, offline connection, retry window). Verify selected connection is online.\n\n### Local ClickHouse unreachable at login\nIf the `Local ClickHouse` connection is listed but unreachable:\n- Use login **Can't login?** to open setup guidance and generate a startup command\n- Restart CH-UI with `--clickhouse-url` or `CLICKHOUSE_URL`\n- Reload login and retry with your ClickHouse credentials\n\n### WebSocket/tunnel fails behind proxy\nYour proxy must forward upgrades on `/connect`:\n- `Upgrade` and `Connection: upgrade` headers\n- long read/send timeouts\n- buffering disabled for tunnel path\n\n### Health check\n```bash\ncurl http://localhost:3488/health\n```\n\n---\n\n## Development\n\nRequirements:\n- Go 1.24+\n- Bun\n\n```bash\ngit clone https://github.com/caioricciuti/ch-ui.git\ncd ch-ui\nmake build\nch-ui\n```\n\nDev mode:\n```bash\nmake dev\n# in another terminal\ncd ui \u0026\u0026 bun install \u0026\u0026 bun run dev\n```\n\nUseful targets:\n- `make build`\n- `make build-frontend`\n- `make build-go`\n- `make test`\n- `make vet`\n- `make clean`\n\n---\n\n## Upgrade\n\n```bash\nch-ui update\n```\n\nThe updater downloads the latest release asset for your OS/arch, verifies checksum when available, and replaces the running binary on disk.\n\n---\n\n## Legal\n\n- Core license: [`LICENSE`](LICENSE)\n- CH-UI licensing details: [`docs/license.md`](docs/license.md)\n- Terms: [`docs/legal/terms-of-service.md`](docs/legal/terms-of-service.md)\n- Privacy: [`docs/legal/privacy-policy.md`](docs/legal/privacy-policy.md)\n\n---\n\n## Contributing\n\nIssues and PRs are welcome.\n\nIf you are contributing features, include:\n- reproduction steps\n- expected behavior\n- migration notes (if schema/API changed)\n- screenshots for UI changes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaioricciuti%2Fch-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaioricciuti%2Fch-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaioricciuti%2Fch-ui/lists"}