Feature Permissions

Feature permissions let you hide or protect specific dashboard sections without changing application code. Features are enabled and public by default — except the AI agent (agent) and control actions (actions), which default to authenticated. Configure only what needs different behavior.

Permissions also carry a read / write classification. Reads are predefined monitoring data; writes are the AI agent, control actions, and arbitrary SQL execution. Under auth=clerk with CHM_CLERK_PUBLIC_READ, anonymous visitors may perform reads but never writes; with auth=none everyone may do both.

Defaults

enabled = true
access  = "public"   (alias: "guest")

A self-hosted deployment with no auth configured works out of the box. Every page is visible to any visitor.

Access values

Configure

Configuration is layered. Later sources win over earlier ones:

built-in allow-all defaults
  → TypeScript config defaults
    → CHM_CONFIG_FILE (TOML or YAML)
      → environment variables

Config file (CHM_CONFIG_FILE)

Point CHM_CONFIG_FILE at a TOML or YAML file. Feature names are lowercase in the file.

[features.agent]
enabled = true
access = "authenticated"

[features.metrics]
enabled = true
access = "guest"

[features.settings]
enabled = false

# /etc/clickhouse-monitor/config.yaml

features:
  agent:
    enabled: true
    access: authenticated
  metrics:
    enabled: true
    access: guest
  settings:
    enabled: false

Environment variable overrides

Env vars override the config file. Feature ids are uppercase in env var names.

# Disable many features at once
CHM_DISABLED_FEATURES=settings,insights

# Require auth for many features at once
CHM_AUTH_REQUIRED_FEATURES=agent,settings

# Override one feature
CHM_FEATURE_AGENT_ACCESS=authenticated
CHM_FEATURE_METRICS_ENABLED=false
CHM_FEATURE_SETTINGS_ACCESS=authenticated

Supported feature ids

Use these ids in TOML/YAML (lowercase) or env vars (uppercase):

Docker examples

docker run -d \
  -e CLICKHOUSE_HOST='http://clickhouse:8123' \
  -e CLICKHOUSE_USER='default' \
  -e CLICKHOUSE_PASSWORD='' \
  -e CHM_CONFIG_FILE='/etc/clickhouse-monitor/config.toml' \
  -v "$PWD/config.toml:/etc/clickhouse-monitor/config.toml:ro" \
  -p 3000:3000 \
  ghcr.io/chmonitor/chmonitor:vX.Y.Z

docker run -d \
  -e CLICKHOUSE_HOST='http://clickhouse:8123' \
  -e CLICKHOUSE_USER='default' \
  -e CLICKHOUSE_PASSWORD='' \
  -e CHM_FEATURE_AGENT_ACCESS='authenticated' \
  -e CHM_FEATURE_SETTINGS_ENABLED='false' \
  -p 3000:3000 \
  ghcr.io/chmonitor/chmonitor:vX.Y.Z

Authentication for authenticated features

Gating UI features with access = "authenticated" requires a user auth provider (for example, Clerk). Set one of:

CHM_AUTH_PROVIDER=clerk
CHM_CLERK_PUBLISHABLE_KEY=pk_live_your_key
CLERK_SECRET_KEY=sk_live_your_key

AGENT_API_TOKEN=your-shared-token

# Call the agent API
curl -H "Authorization: Bearer your-shared-token" \
  https://your-deployment.example.com/api/v1/agent

See Authentication for the full auth model, including API keys and reverse-proxy options.

Common policies

Behavior when a feature is disabled or gated

• Disabled (enabled = false): removed from navigation and command search. Direct page visits show a disabled screen. API routes return a blocked response before querying ClickHouse or the agent.
• Authenticated (access = "authenticated"): unauthenticated visitors see the feature in navigation (so they know to sign in) but cannot load data. API routes reject unauthenticated requests.

Related