Skip to content

Admin Guide

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

Admin is part of the open-source core: no Pro license is needed and nothing in it is limited by plan. It is only visible to users with the admin role. A few settings inside it (SSO, GitHub sync, Brain budgets per role or person and dollar limits) need Pro.

Open Admin from the Settings group in the rail. Its sections are listed in the sidebar, and each one has its own URL (/admin?section=...):

Section What it holds
Overview System statistics and the cluster topology
Connections Every ClickHouse connection, direct or remote agent, with its status; details open in a side sheet
Users Application users with role overrides, and ClickHouse users
Brain AI providers, models, model roles, prices and the system prompt
Brain budgets Token and dollar limits on Brain per person, role or everyone
Brain usage Tokens and cost per person or role and model
GitHub GitHub sync for models, per connection
MCP Server Connecting a client as yourself (OAuth), service keys, and the OAuth grants and keys in one table
Settings Data retention and SSO

The Connections section’s id is tunnels; /admin?section=connections opens it too.

The Overview section shows key metrics:

Metric Description
Users Count Total users with sessions
Connections Total ClickHouse connections
Online Connections with active tunnels
Login Count Total login events
Query Count Total queries executed
GET /api/admin/stats

View all ClickHouse connections with their type (Embedded for the one from server config, Direct or Agent), target, online status, creation date, and last seen timestamp.

Add connection defaults to Direct URL: give it a name and a ClickHouse HTTP(S) URL the server can reach, and it connects right away. Choose Remote agent instead for a ClickHouse behind a firewall; CH-UI then shows a token to run ch-ui connect with next to that server. Agent rows have buttons to show or regenerate the token. See Direct vs tunnel connections.

Edit on a row opens a sheet. Direct connections can be renamed and pointed at another ClickHouse URL; saving a new URL restarts that connection’s connector. Agent connections can only be renamed, and the agent and its token keep working. The embedded connection has no Edit or Delete: it shows Server config, because its name and URL come from clickhouse_url and connection_name in the server config (hover the label to see that).

A new URL that reaches a different ClickHouse server resets the connection, because what CH-UI stored for it belongs to the old server. Saving signs everyone out of that connection and clears its role overrides, per-person SSO user records, the SSO account, MCP keys and their OAuth tokens, and dashboard share links. Background accounts set to a service account are switched to Disabled. Nothing is sent to either ClickHouse server; set these up again for the new one. The audit log gets a connection.reset entry with the counts. A URL for the same server (only case, a default port or a trailing slash differs) clears nothing. The same reset happens when first-run setup points the connection elsewhere, and on startup when clickhouse_url for the embedded connection names a different server than before. After saving, a message lists what was cleared.

Agents from v2.33.0 report the ClickHouse server they dial (scheme, host, port and path, no credentials), and the row shows it as the target. When an agent signs in pointing at a different server than it reported before, the same reset runs before the agent can run anything, and the audit entry names both servers. Older agents still connect but cannot be checked; an online one that has never reported shows Update agent. See Repointing an agent.

A connection that moved to a different server, by any of these paths, shows a Server changed badge for 7 days.

Each connection row has a Background accounts button. It sets which ClickHouse account unattended jobs (schedules, models, pipeline sinks, governance, Cluster Health, telemetry monitors, performance monitoring and weekly reports) use on that connection. See Background Accounts.

Each row also has an SSO button: the ClickHouse account SSO sessions use on that connection, and whether SSO people share it or get their own ClickHouse users, with the group to role mapping, Show setup SQL and Verify.

GET /api/admin/connections

Adding a person? Invite a teammate is the short version of this section.

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

People who sign in with SSO are listed one row per person, by email, with an SSO badge and the ClickHouse account they query as: the shared service account, or, on connections with per-person ClickHouse users, one line per connection with their own user, its roles, the last sync and a locked badge once the sweep locked it. Their role override applies to that person only. An override set on the service account name applies to password logins as that account, not to SSO people.

Remove access on an SSO person drops their ClickHouse users on every connection and signs them out at once (DELETE /api/admin/users/sso/{email}/access). It also revokes the MCP keys and OAuth tokens that run as them on those connections. A connection that is offline is reported in the response, and the removal still takes effect in CH-UI right away: their ClickHouse user there is refused for every CH-UI path (MCP, OAuth refresh, share links, run-as-me), and the hourly sweep drops it once the connection is back. Their IdP account is untouched: a later sign-in provisions them again, with their current groups.

The application list shows the current connection: its password users and every SSO person. Switch connection to manage another connection’s users.

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

Role Access
admin Full access: schema operations, user management, brain providers, governance policies
analyst Query execution, saved queries, dashboards, brain chat
viewer Read-only access

Overrides for ClickHouse users (password login) apply per connection: an admin role on one connection does nothing for the same username on another. Overrides for SSO people apply on all connections, since the identity provider verified who they are. Connections added from the login page (sign-in with a ClickHouse URL) take no overrides and never grant admin; the most a user gets there is analyst.

# Set role (connection_id defaults to your current connection; ignored for sso:<email>)
PUT /api/admin/user-roles/{username}
{ "role": "admin", "connection_id": "<connection id>" }
# Remove override (reverts to the detected role)
DELETE /api/admin/user-roles/{username}?connection_id=<connection id>

GET /api/admin/user-roles lists every override with connection_id and connection_name; connection_id is empty for SSO overrides.

For an SSO person, {username} is sso:<email>, URL-encoded (for example sso%3Aana%40example.com). GET /api/admin/users returns this key as username, plus display_name, clickhouse_user and via_sso.

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

Lost the admin role, or nobody who has it can sign in? Run ch-ui reset-admin on the server. See Recover the admin role.

Manage ClickHouse users directly from the admin UI. Passwords never reach CH-UI’s server (v2.31.0+): the browser generates a password or takes the one you type, hashes it with a random salt, and sends only the hash. A generated password is shown once after saving. Commands shown in the UI and the audit log carry BY '***' SALT '***'.

POST /api/admin/clickhouse-users
{
"name": "analyst_user",
"auth": {"method": "sha256_hash", "hash": "<64 hex>", "salt": "<salt>"},
"default_roles": ["analyst_role"]
}
Field Description Default
name Username Required
auth.method sha256_hash, double_sha1_hash, bcrypt_hash or no_password Required with auth
auth.hash sha256_hash: hex of sha256(password + salt), 64 characters. double_sha1_hash: 40 hex. bcrypt_hash: $2b$12$... None
auth.salt sha256_hash only, optional: letters, digits and . _ ~ + / = -, at most 128 None
default_roles Array of role names or ["ALL"] None

The operation generates up to three commands: CREATE USER (never IF NOT EXISTS, so a taken name fails with 409), GRANT roles, and ALTER USER SET DEFAULT ROLE.

Without auth, the user is created with no password.

Removed in v2.33.0: the plaintext password and auth_type fields, deprecated since v2.31.0. A request that sends either one gets a 400 and nothing is run, here, on Change Password and on Governance user creation. Hash the password on the client and send auth instead, so the CH-UI server never sees it.

PUT /api/admin/clickhouse-users/{username}/password
{
"auth": {"method": "sha256_hash", "hash": "<64 hex>", "salt": "<salt>"},
"if_exists": true
}

The same auth object as Create User, and it is required: a request without it is a 400. {"method": "no_password"} removes the password.

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

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

Each ClickHouse user row has an Edit grants button. It opens the user in Governance → Access control (/governance?section=rbac&user=<name>), where roles, privileges, default roles, row policies, quotas and settings profiles are edited through a reviewed change set. Pro, admin only. See Access Control Editor.

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. Admin → Settings shows a status table (what each table holds, its window, the default, and the last cleanup), and Edit retention opens a sheet where you change the windows or reset them to defaults. The same is available through 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.

Table Default window
audit_logs 90 days
alert_events 60 days
alert_dispatch_jobs 30 days
schedule_runs 60 days
pipeline_runs 90 days
pipeline_run_logs 30 days
model_runs 90 days
model_run_results 30 days
github_sync_logs 30 days
gov_schema_changes 180 days
operations_reports 180 days
incident_annotations (incident_deployment_annotations, by when the deployment happened) 180 days
resolved_investigations (performance_investigations that are resolved, by resolution time; open and monitoring ones are never pruned) 180 days
gov_query_log (queries synced from ClickHouse for governance) 30 days
gov_policy_violations (queries that broke a governance policy) 30 days
rbac_snapshots (access history; at most 500 rows per connection whatever the window, and the newest is always kept) 180 days
alert_evaluations (evaluation history of health checks and SQL alerts) 30 days
report_deliveries (report delivery history; the rendered copy of each run is still cleared after 7 days) 90 days

The last five (v2.30.0+, and v2.31.0+ for report_deliveries; fixed windows before that) are pruned by the job that owns each table, not by the hourly cleanup: the governance sync prunes the query log, violations and access history, access history is also pruned on every new snapshot, the cluster health harvester prunes alert evaluations, and the report runner prunes report deliveries. They show the owning job under Last cleanup and are not counted in the run stats GET returns.

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

SSO status and configuration also live in Admin → Settings: a status panel when SSO is on, and a Configure SSO sheet with the fields grouped by provider, role mapping and service account. See Single Sign-On.

Admin → MCP Server manages the embedded MCP endpoint: counters for active keys, OAuth grants, keys expiring soon and keys used in the last day, the endpoint URL with config snippets per client, and the tables of service keys and OAuth grants where you create, rotate and revoke access. See MCP Server.

Brain’s AI configuration (providers, models, model roles, prices and skills) lives in the Admin → Brain section, restricted to admins. Configure a provider (Anthropic, OpenAI, OpenAI-compatible, or Ollama), sync and activate models, and author skills there.

Admin → Brain budgets (/admin?section=brain-budgets) lists the budget rules with each one’s use this period, and Admin → Brain usage (/admin?section=brain-usage) shows tokens and cost by person or by role. Global token budgets work on every plan; role and person rules and dollar limits need Pro.

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

ch-ui server status
ch-ui server restart
ch-ui server stop
ch-ui service status
ch-ui service restart
ch-ui reset-admin # recover the admin role, see Can't login?

If no CH-UI admin can sign in, ch-ui reset-admin hands the role back. See Can’t login? and the CLI reference.

The Overview section includes a Cluster Topology panel 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.

  • Keep at least one admin override account
  • Rotate provider API keys periodically
  • Use a different APP_SECRET_KEY per environment (it encrypts API keys, tokens and session credentials). To change it, follow Rotating the app secret key: replacing the key alone makes every stored secret unreadable
  • Keep governance sync healthy before relying on policy alerts
  • Test alert channels before enabling rules