Admin Guide

Admin is where operators manage users, connections, AI providers, and system configuration.

Available on all plans (limits scale by plan).

System Statistics

The admin dashboard shows key metrics:

GET /api/admin/stats

Connections Overview

View all ClickHouse connections with their tunnel status, creation date, and last seen timestamp.

GET /api/admin/connections

Users

CH-UI provides two user views:

• Application users — active users with role overrides and login history
• ClickHouse users — live users from the connected ClickHouse instance

Role Overrides

Set CH-UI role overrides to control application-level permissions:

# Set role
PUT /api/admin/user-roles/{username}
{ "role": "admin" }

# Remove override (reverts to viewer)
DELETE /api/admin/user-roles/{username}

Safety: cannot remove the last admin role. Role changes refresh active sessions immediately.

ClickHouse User Management

Manage ClickHouse users directly from the admin UI.

Create User

POST /api/admin/clickhouse-users
{
  "name": "analyst_user",
  "password": "secure_password",
  "auth_type": "sha256_password",
  "default_roles": ["analyst_role"],
  "if_not_exists": true
}

When auth_type is omitted, it's inferred: sha256_password if a password is provided, no_password otherwise.

The operation generates up to three commands: CREATE USER, GRANT roles, and ALTER USER SET DEFAULT ROLE.

Change Password

PUT /api/admin/clickhouse-users/{username}/password
{
  "password": "new_password",
  "auth_type": "sha256_password",
  "if_exists": true
}

Delete User

DELETE /api/admin/clickhouse-users/{username}?if_exists=true

Safety: cannot delete the current session's ClickHouse user.

Data Retention

CH-UI's SQLite database accumulates append-only history (audit logs, alert events, run logs). The retention manager prunes each table on its own window, from the Admin UI or the API:

GET /api/admin/retention
PUT /api/admin/retention

GET returns the current config, the built-in defaults, and stats from the most recent run. PUT accepts partial bodies — omitted fields keep their current value.

Set a window to 0 to keep that table forever (pruning disabled); the maximum is 3650 days. The background job runs hourly and deletes in small batches so it never holds the SQLite write lock for long. Config changes are recorded in the audit log (retention.config_update).

Brain configuration

Brain's AI configuration — providers, models, and skills — lives in the Admin → Brain tab, restricted to admins. Configure a provider (OpenAI, OpenAI-compatible, or Ollama), sync and activate models, and author skills there.

See Brain → Configuring AI for providers/models and Brain → Skills for authoring reusable expertise.

Operational Commands

ch-ui server status
ch-ui server restart
ch-ui server stop

ch-ui service status
ch-ui service restart

Cluster Topology

The Overview tab includes a Cluster Topology section that surfaces what system.clusters reports for the connection: every shard, every replica, with host / address / port / shard_num / replica_num / is_local. A green dot marks the node that's currently serving your session. Single-node deployments show "Single-node setup detected" with just the hostname.

For multi-pod setups behind a load balancer, see ClickHouse Clusters & Load Balancers for the sticky-routing config that keeps your session pinned to one pod.

Production Notes

• Keep at least one admin override account
• Rotate provider API keys periodically
• Rotate APP_SECRET_KEY per environment (encrypts API keys and session credentials)
• Keep governance sync healthy before relying on policy alerts
• Test alert channels before enabling rules