LibreChat Admin Panel

The LibreChat Admin Panel is a standalone browser-based management interface for LibreChat. It connects to the same database as LibreChat itself and provides a GUI for the administrative tasks that power granular access control: user and group administration, role management, configuration overrides scoped to roles or groups, and system-level capability grants.

What It Does

The admin panel is a thin client: all data lives in LibreChat's database, and every action goes through the versioned /api/admin/* endpoints on the LibreChat API server. It gives administrators a single place to:

• Manage configuration: view and edit every LibreChat setting through a dynamic, schema-driven form. New fields added to the config schema appear automatically, no admin-panel release required.
• Apply per-principal overrides: scope configuration overrides to specific roles or groups, with a priority-based cascade that determines the final resolved value each user sees at login.
• Administer users: list, search, and view every account on the instance.
• Manage groups: create and delete groups, add/remove members, and use groups as first-class principals in ACLs and overrides.
• Manage roles: create custom roles beyond the built-in USER / ADMIN, edit their feature-permission matrix, and assign users to roles.
• Issue system grants: delegate admin capabilities (e.g. manage:users, read:usage, manage:mcpservers) to specific users, groups, or roles without making them full admins.
• Authenticate: log in with a local LibreChat admin account, or via OpenID SSO / SAML / supported OAuth providers when those are enabled on the LibreChat instance.

For the underlying permission model (principals, resource ACLs, capabilities, and how the layers compose), see the Access Control page.

Architecture

┌──────────────────┐         ┌──────────────────┐         ┌──────────────┐
│  Admin Panel     │ ───────▶│  LibreChat API   │ ───────▶│   MongoDB    │
│  (Bun + Vite)    │  HTTPS  │  /api/admin/*    │         │  (shared DB) │
└──────────────────┘         └──────────────────┘         └──────────────┘
       │                             │
       │ OAuth/OIDC/SAML redirect    │ Verifies admin access
       └─────────────────────────────┘

The admin panel runs as a separate service; it does not share a process with LibreChat. Admin capabilities are verified on the LibreChat side via the access:admin system grant or SystemRoles.ADMIN role, so the panel cannot grant itself privileges it shouldn't have.

The admin API surface exposed by LibreChat is:

Getting Started

Prerequisites

• A running LibreChat instance on v0.8.5 or later (admin APIs are not available in earlier versions)
• Network access from the admin-panel container/host to the LibreChat API
• An admin account on LibreChat: either the first-registered user (auto-admin), a user with role: 'ADMIN' set in Mongo, or a principal that has been granted the access:admin capability

Run with Docker (recommended)

Using the published image from GHCR:

# 1. Create an env file
cp .env.example .env
 
# 2. Edit .env and set at minimum:
#    SESSION_SECRET=<random string, min 32 characters>
#    VITE_API_BASE_URL=http://host.docker.internal:3080
 
# 3. Start it
docker compose up -d   # http://localhost:3000
docker compose down    # stop

Standalone docker run:

docker run -p 3000:3000 \
  --add-host=host.docker.internal:host-gateway \
  -e SESSION_SECRET=replace-with-32-char-random-string \
  -e VITE_API_BASE_URL=http://host.docker.internal:3080 \
  ghcr.io/clickhouse/librechat-admin-panel:latest

Run Locally for Development

git clone https://github.com/ClickHouse/librechat-admin-panel.git
cd librechat-admin-panel
cp .env.example .env    # then edit
bun install
bun dev                 # http://localhost:3000

Environment Variables

LibreChat Redirect URL

When the admin panel is hosted on a separate URL from LibreChat, set ADMIN_PANEL_URL in the LibreChat API environment. Use the external admin panel base URL, including any path prefix, and omit the trailing slash:

ADMIN_PANEL_URL=https://admin.example.com/admin

For Helm deployments, set librechat.adminPanelUrl in your values file. The chart renders it as ADMIN_PANEL_URL for LibreChat's admin OAuth flow:

librechat:
  adminPanelUrl: https://admin.example.com/admin

For OpenID SSO, register ${DOMAIN_SERVER}/api/admin/oauth/openid/callback with your identity provider.

Cache Controls

These mirror LibreChat's cache env vars. ADMIN_PANEL_* variants take precedence, falling back to the shared LibreChat equivalents when unset.

Authentication

The admin panel reuses LibreChat's authentication stack and does not have its own user database. Two login paths are supported:

• Local accounts: username/password against any LibreChat user whose account passes the admin-access check.
• Single sign-on: OpenID Connect, SAML, and the social OAuth providers already configured on your LibreChat instance. Set ADMIN_SSO_ONLY=true to hide the password form entirely.

Admin access is verified server-side by LibreChat for every request. The account must either:

1. Have role: 'ADMIN' in MongoDB, or
2. Hold the access:admin system grant (assigned to another principal via the admin panel itself; see System Grants).

Sessions are cookie-based, encrypted with SESSION_SECRET, and idle-expire per ADMIN_SESSION_IDLE_TIMEOUT_MS.

Configuration Management

The panel renders the LibreChat config as a dynamic form driven by the config schema. This has two useful properties:

• Forward-compatible: when LibreChat ships a new config field, the panel picks it up automatically from the schema. No admin-panel upgrade or redeploy is required.
• Layered overrides: the base config (from librechat.yaml) can be shadowed by per-principal overrides scoped to a role or group. When a user logs in, overrides are resolved in priority order and merged on top of the base to produce the effective config that user sees.

This is the surface behind LibreChat's DB-backed per-principal configuration override system. Typical use cases:

• Give a "Research" group higher recursionLimit and additional endpoints
• Let a "FinanceAdmins" role manage MCP servers while regular users can only use them
• Scope stricter interface permissions to external-contractor groups

Related

• Access Control: the permission model the admin panel is built on
• Interface Configuration: the feature flags the panel edits
• Authentication: user authentication on LibreChat
• v0.8.5 changelog: admin API foundations
• GitHub: ClickHouse/librechat-admin-panel: source, issues, releases