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

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

Server Config

Default config path:

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

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

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	built-in dev value	Encrypts session credentials; must change in production
`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

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)

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

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_admin_groups: [ch-ui-admins]
oidc_analyst_groups: [data-analysts]

Full setup in Single Sign-On.

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_ALLOWED_DOMAINS` / `OIDC_ADMIN_GROUPS` / `OIDC_ANALYST_GROUPS` / `OIDC_GROUPS_CLAIM`	OIDC mapping
`CHUI_SQLITE_MAX_OPEN_CONNS`	Max SQLite connections (default 8)
`CHUI_VITE_MINIFY`	Toggle frontend build minification

Connector Config

Default config path:

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

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`	`wss://cloud.ch-ui.com/connect`	Server gateway endpoint
`insecure_skip_verify`	`false`	`false`	Only for insecure dev TLS setups

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`	TLS skip verify (`true/1/yes`)

Minimal Production Templates

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`)

tunnel_token: "cht_replace_me"
clickhouse_url: "http://127.0.0.1:8123"
tunnel_url: "wss://ch-ui.yourcompany.com/connect"

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

ch-ui server status
ch-ui service status