Skip to content
chmonitor chmonitor

Browser Connections

Open as Markdown

Add personal ClickHouse connections in the browser and query them via the chmonitor proxy — without touching server config.

Routes(app shell, connection selector in header)
Feature id(none — part of the app shell, not a gated feature)
Default accesspublic
Requires authNo
System tablesNone
ClickHouse grantsWhatever the connection’s user has

What it does

Section titled “What it does”

chmonitor normally connects to ClickHouse using the server-side CLICKHOUSE_HOST, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD environment variables. Browser Connections lets individual users add extra ClickHouse hosts directly in their browser, without changing server config.

When a user adds a connection, the credentials are stored in encrypted browser localStorage (AES-256-GCM with a device-bound key). When they query, chmonitor creates a short-lived session token server-side; subsequent chart/table requests use the token instead of sending the password on every request. All queries still proxy through the chmonitor server — the browser never opens a direct connection to ClickHouse.

This is useful for:

  • Personal development: quickly point chmonitor at a local ClickHouse instance
  • Testing: connect to a staging cluster without redeploying
  • Demos: show a read-only user’s view without sharing admin credentials

The connection selector in the header shows both server-configured hosts and browser-stored connections. Switching between them changes which host all dashboard pages query.

Permissions & access

Section titled “Permissions & access”

Browser Connections is part of the app shell and has no dedicated feature id. It cannot be disabled independently.

If you want to prevent users from switching hosts at all, restrict access to the dashboard itself using the global auth model (CHM_AUTH_PROVIDER) rather than trying to remove the connection selector.

Configuration

Section titled “Configuration”

No server-side configuration. Browser connections are managed entirely in the client.

For teams, configure hosts server-side:

Terminal window
CLICKHOUSE_HOST=https://host1.example.com:8443,https://host2.example.com:8443
CLICKHOUSE_USER=chmonitor,chmonitor
CLICKHOUSE_PASSWORD=secret1,secret2
CLICKHOUSE_NAME=Production,Staging

Server-configured hosts appear for all users without any browser setup.

Notes & limitations

Section titled “Notes & limitations”
  • Credentials are encrypted in browser localStorage, but XSS on the dashboard could still expose decrypted values in memory. Do not use write-capable production credentials on shared or untrusted devices.
  • Session tokens expire after 15 minutes; the client refreshes them automatically when needed.
  • Browser connections are per-browser, per-device. They are not shared across users or synchronized.
  • All queries still go through the chmonitor server proxy — the browser never connects directly to ClickHouse. The chmonitor server must have network access to the target ClickHouse host.
  • For team or multi-user deployments, prefer server-side CLICKHOUSE_HOST/CLICKHOUSE_USER/CLICKHOUSE_PASSWORD configuration so all users share the same host list.
  • If chmonitor is deployed behind authentication (CHM_AUTH_PROVIDER=clerk or proxy), the proxy still enforces auth before forwarding any query, regardless of which host is selected.
Section titled “Related”