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

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
`APP_SECRET_KEY`	Session/password encryption secret
`ALLOWED_ORIGINS`	Comma-separated CORS origins
`TUNNEL_URL`	Override gateway URL

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

Configuration

On this page