Admin Guide

Users, ClickHouse user management, Brain providers, Langfuse, and operational controls

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

Included in the free Community edition.

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 Provider Management

Configure AI providers for all users.

Provider Kinds

Kind	Base URL	Auth
`openai`	`https://api.openai.com` (default)	API key
`openai_compatible`	Any URL	API key
`ollama`	`http://localhost:11434` (default)	None

Provider CRUD

# Create
POST /api/admin/brain/providers
{
  "name": "OpenAI",
  "kind": "openai",
  "apiKey": "sk-...",
  "isActive": true,
  "isDefault": true
}

# Update
PUT /api/admin/brain/providers/{id}
{ "name": "Updated Name", "isActive": false }

# Delete (cascades to all models)
DELETE /api/admin/brain/providers/{id}

API keys are encrypted at rest with the app secret key.

Sync Models

Fetch available models from a provider:

POST /api/admin/brain/providers/{id}/sync-models

Connects to the provider API, imports model list, and auto-selects a recommended default if none is set.

Model Management

# Update single model
PUT /api/admin/brain/models/{id}
{ "displayName": "GPT-4o", "isActive": true, "isDefault": true }

# Bulk action
POST /api/admin/brain/models/bulk
{ "providerId": "uuid", "action": "activate_recommended" }

Bulk actions: activate_all, deactivate_all, activate_recommended.

Setting isDefault=true automatically sets isActive=true. Setting isActive=false clears isDefault.

Brain Skills

Skills are custom system prompt extensions appended to every Brain chat.

# List
GET /api/admin/brain/skills

# Create
POST /api/admin/brain/skills
{
  "name": "SQL Standards",
  "content": "Always use table aliases. Prefer CTEs over subqueries.",
  "isActive": true,
  "isDefault": false
}

# Update
PUT /api/admin/brain/skills/{id}
{ "content": "Updated instructions", "isActive": true }

Only one skill can be active at a time. Mark a skill as default to auto-activate it.

Langfuse Configuration

Configure Langfuse for Brain observability (traces, token usage, scoring).

Save Configuration

PUT /api/admin/langfuse
{
  "publicKey": "pk_...",
  "secretKey": "sk_...",
  "baseUrl": "https://cloud.langfuse.com"
}

Secret key is encrypted at rest. Partial updates are supported — omit secretKey to keep the existing one.

Test Connection

POST /api/admin/langfuse/test
{
  "publicKey": "pk_...",
  "secretKey": "sk_..."
}

If secretKey is omitted, the stored (encrypted) key is used.

Disable

DELETE /api/admin/langfuse

Removes all configuration and disables observability.

What Gets Traced

See Brain > Langfuse Integration for full details on traces, generations, and scores.

Operational Commands

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

ch-ui service status
ch-ui service restart

Production Notes

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

Admin Guide

On this page