Skip to content
CH-UI

Configuration

CH-UI works without config files out of the box. You only need config files when you want production defaults, service-managed startup, or want to avoid passing flags every time.

Priority Order

Section titled “Priority Order”

Values are resolved in this order (highest wins):

  • Server: CLI flags > environment variables > server.yaml > built-in defaults
  • Connector: CLI flags > environment variables > config.yaml > built-in defaults

.env file

Section titled “.env file”

On startup the ch-ui binary reads a .env file from the current working directory, if one exists, for both the server and the connector. Each KEY=value line is set as an environment variable only when that variable is not already set, so real environment variables always take precedence. Lines starting with # are ignored and surrounding quotes are stripped.

# .env
APP_URL=https://ch-ui.yourcompany.com
APP_SECRET_KEY="replace-with-a-long-random-secret"

Server Config

Section titled “Server Config”

Default config path:

  • macOS: ~/.config/ch-ui/server.yaml
  • Linux: /etc/ch-ui/server.yaml

Server config explained

Section titled “Server config explained”
port: 3488
app_url: https://ch-ui.yourcompany.com
database_path: /var/lib/ch-ui/ch-ui.db
clickhouse_url: http://localhost:8123
connection_name: Local ClickHouse
app_secret_key: "change-this-in-production"
allowed_origins:
  - https://ch-ui.yourcompany.com
# optional override:
# tunnel_url: wss://ch-ui.yourcompany.com/connect

Unknown top-level keys are ignored, but the server logs a warning at startup listing them (Config file has unknown keys; they are ignored), so a typo in a key name shows up in the log.

Key Example Default Why it matters
port 3488 3488 HTTP port used by CH-UI server
app_url https://ch-ui.yourcompany.com http://localhost:<port> Public URL for links and tunnel URL inference
database_path /var/lib/ch-ui/ch-ui.db ./data/ch-ui.db Where CH-UI stores app state
clickhouse_url http://localhost:8123 http://localhost:8123 Embedded local connection target
connection_name Local ClickHouse Local ClickHouse Display name for embedded local connection
app_secret_key random long string auto-generated Encrypts stored credentials. When unset, CH-UI generates a random key on first start and persists it to .app_secret_key next to the database. Back it up with the DB
allowed_origins ["https://ch-ui.yourcompany.com"] empty CORS allowlist
tunnel_url wss://ch-ui.yourcompany.com/connect derived from port Explicit tunnel endpoint advertised to agents
tls_cert_file /etc/ch-ui/tls/server.crt empty PEM cert for native TLS (with tls_key_file)
tls_key_file /etc/ch-ui/tls/server.key empty PEM key for native TLS
session_max_age 86400 604800 (7 days) Session lifetime in seconds

Native TLS

Section titled “Native TLS”

Set both tls_cert_file and tls_key_file to have CH-UI serve HTTPS directly. If unset, CH-UI serves plaintext HTTP and expects a reverse proxy to terminate TLS; when bound to a non-loopback address without TLS it logs a startup warning. See Security.

Audit forwarding (SIEM)

Section titled “Audit forwarding (SIEM)”

Optionally stream audit events to your tooling (the authoritative copy stays in the database). See Monitoring & SIEM.

audit_forward_stdout: true
audit_log_file: /var/log/ch-ui/audit.jsonl
audit_webhook_url: https://siem.example.com/hook

OIDC SSO

Section titled “OIDC SSO”
oidc_issuer_url: https://accounts.google.com
oidc_client_id: your-client-id
oidc_client_secret: your-client-secret
oidc_redirect_url: https://ch-ui.yourcompany.com/api/auth/oidc/callback
# Optional:
oidc_allowed_domains: [yourcompany.com]
oidc_groups_claim: groups
oidc_admin_groups: [ch-ui-admins]
oidc_analyst_groups: [data-analysts]
oidc_connection_id: <connection-id>

oidc_groups_claim is the ID-token claim that holds group memberships (default groups). oidc_connection_id picks the connection SSO sessions use; when unset, CH-UI uses the embedded connection, or the first connection if there is no embedded one. SSO login is Pro.

Full setup in Single Sign-On.

Server environment variables

Section titled “Server environment variables”
Variable Description
PORT HTTP port
APP_URL Public base URL
DATABASE_PATH SQLite path
CLICKHOUSE_URL Local ClickHouse URL for embedded connector
CONNECTION_NAME Display name for embedded local connection
CONNECITION_NAME Backward-compatible typo alias for CONNECTION_NAME
APP_SECRET_KEY Session/password encryption secret
ALLOWED_ORIGINS Comma-separated CORS origins
TUNNEL_URL Override gateway URL
TLS_CERT_FILE / TLS_KEY_FILE PEM cert/key for native TLS
AUDIT_FORWARD_STDOUT / AUDIT_LOG_FILE / AUDIT_WEBHOOK_URL Audit forwarding sinks
OIDC_ISSUER_URL / OIDC_CLIENT_ID / OIDC_CLIENT_SECRET / OIDC_REDIRECT_URL OIDC SSO
OIDC_CONNECTION_ID Connection SSO sessions use (default: the embedded connection, else the first)
OIDC_ALLOWED_DOMAINS / OIDC_ADMIN_GROUPS / OIDC_ANALYST_GROUPS / OIDC_GROUPS_CLAIM OIDC mapping
CHUI_LICENSE_FILE Path to a Pro license JSON file (e.g. a mounted Kubernetes Secret)
CHUI_LICENSE Pro license JSON inline (file takes precedence)
SESSION_MAX_AGE Session lifetime in seconds (default 604800, i.e. 7 days)
NODE_ENV development enables dev mode (relaxed CORS and security headers). The server command’s --dev flag overrides it; NODE_ENV is honored for other entry points
CHUI_SQLITE_MAX_OPEN_CONNS Max SQLite connections (default 8)
CHUI_VITE_MINIFY Build-time: toggle frontend build minification (0 disables)
VITE_BASE_PATH Build-time: base path for hosting the UI under a sub-path (e.g. /ch-ui), read by ui/vite.config.ts

Connector Config

Section titled “Connector Config”

Default config path:

  • macOS: ~/.config/ch-ui/config.yaml
  • Linux: /etc/ch-ui/config.yaml

Connector config explained

Section titled “Connector config explained”
tunnel_token: "cht_your_token"
clickhouse_url: "http://127.0.0.1:8123"
tunnel_url: "wss://ch-ui.yourcompany.com/connect"
# insecure_skip_verify: false
Key Example Default Why it matters
tunnel_token cht_... none (required) Auth key created on server (ch-ui tunnel create)
clickhouse_url http://127.0.0.1:8123 http://localhost:8123 Local ClickHouse for this VM
tunnel_url wss://ch-ui.yourcompany.com/connect ws://127.0.0.1:3488/connect Your CH-UI server’s /connect gateway endpoint. Set it for any remote server
insecure_skip_verify false false Skips TLS certificate checks on both the tunnel and the connector’s requests to ClickHouse. Only for dev setups with self-signed certs

Connector environment variables

Section titled “Connector environment variables”
Variable Description
TUNNEL_TOKEN Tunnel token (cht_...)
CLICKHOUSE_URL ClickHouse HTTP endpoint
TUNNEL_URL WebSocket URL to /connect
TUNNEL_INSECURE_SKIP_VERIFY Same as insecure_skip_verify (true, 1 or yes)

The server has no equivalent setting. There is no server-side INSECURE_SKIP_VERIFY, and connections the server runs itself (the embedded connection) always verify ClickHouse TLS certificates.

Minimal Production Templates

Section titled “Minimal Production Templates”

Server (/etc/ch-ui/server.yaml)

Section titled “Server (/etc/ch-ui/server.yaml)”
port: 3488
app_url: https://ch-ui.yourcompany.com
database_path: /var/lib/ch-ui/ch-ui.db
connection_name: Local ClickHouse
app_secret_key: "replace-with-a-long-random-secret"
allowed_origins:
  - https://ch-ui.yourcompany.com

Connector (/etc/ch-ui/config.yaml)

Section titled “Connector (/etc/ch-ui/config.yaml)”
tunnel_token: "cht_replace_me"
clickhouse_url: "http://127.0.0.1:8123"
tunnel_url: "wss://ch-ui.yourcompany.com/connect"
Section titled “Recommended Production Values”
  • Rotate APP_SECRET_KEY per environment.
  • Use wss:// for all connector tunnels.
  • Keep connector close to ClickHouse to reduce latency.
  • Use non-default file paths managed by system services.

Validation Commands

Section titled “Validation Commands”
ch-ui server status
ch-ui service status