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:

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

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:

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

# 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
}

Field	Description	Default
`name`	Username	Required
`password`	Password (empty for `no_password`)	—
`auth_type`	`no_password`, `plaintext_password`, `sha256_password`, `double_sha1_password`	Inferred from password
`default_roles`	Array of role names or `["ALL"]`	—
`if_not_exists`	Skip if user exists	`false`

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.

Brain's AI configuration — providers, models, managed-AI billing, and skill packs — is managed per organization on the console AI page (/orgs/{slug}/ai), restricted to org owners/admins. It is no longer part of the workspace Admin panel.

See Brain → Configuring AI for providers/models and Brain → Skill packs for authoring reusable expertise (curated and custom packs, core vs on-demand loading).

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