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.
Sections
Section titled “Sections”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.
System Statistics
Section titled “System Statistics”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/statsConnections Overview
Section titled “Connections Overview”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/connectionsAdding 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.
Role Overrides
Section titled “Role Overrides”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.
ClickHouse User Management
Section titled “ClickHouse User Management”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 '***'.
Create User
Section titled “Create User”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.
Change Password
Section titled “Change Password”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 User
Section titled “Delete User”DELETE /api/admin/clickhouse-users/{username}?if_exists=trueSafety: cannot delete the current session’s ClickHouse user.
Roles and grants
Section titled “Roles and grants”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.
Data Retention
Section titled “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. 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/retentionPUT /api/admin/retentionGET 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.
MCP Server
Section titled “MCP Server”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 configuration
Section titled “Brain configuration”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.
Operational Commands
Section titled “Operational Commands”ch-ui server statusch-ui server restartch-ui server stop
ch-ui service statusch-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.
Cluster Topology
Section titled “Cluster Topology”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.
Production Notes
Section titled “Production Notes”- Keep at least one admin override account
- Rotate provider API keys periodically
- Use a different
APP_SECRET_KEYper 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
