Admin UI
The Admin UI is the web control panel where administrators run an AION installation: they create users, set up agent profiles and skills, connect integrations (MCP servers, LLM providers, SMTP, SSO), schedule jobs and check system health. It is separate from the Chat UI, which is what end users chat in. This page is for administrators and, in the later sections, for developers and IT staff who deploy or extend the panel.
- Administrators: start with What can an administrator do? and First login & default admin.
- IT / security: read Admin auth (always on), Change password flow, One-click update and Security considerations.
- Developers: see Next.js Architecture, Configuration and Troubleshooting.
The /admin panel is always protected (Grafana style): all /admin/* endpoints require a Bearer token and the admin role.
See the sections Admin auth (always on),
First login & default admin and
Change password flow below.
Why is the Admin UI separate from the Chat UI?
Decision: The system has two separate interfaces:
- Chat UI - For end users (chat, conversation)
- Admin UI - For administrators (management, configuration)
Why separate?
Why separate:
| Reason | Explanation |
|---|---|
| Separation of responsibilities | Users only use the chat, administrators manage the system |
| Security | Administration operations require elevated privileges and different roles |
| User experience | End users must not be confused by technical configuration options |
| Access control | The Admin UI requires a separate authentication and authorization policy |
Distinct roles
| Interface | Who uses it | What they can do |
|---|---|---|
| Chat UI | End users | Messaging, file upload, management of personal sessions and personal credentials |
| Admin UI | Administrators | Management of users (including the per-user API key policy), profiles, skills, cron jobs, global monitoring and security |
What can an administrator do?
1. Dashboard (Overview)
Path: /
Features:
- Real-time summary view of system metrics.
- Count of active profiles, registered skills, and installed MCP servers.
- Visualization of the global system security score.
- Log of the latest system health checks.
2. User Management
Path: /users
Features:
- Create new user accounts (password mode only: with SSO active, accounts are created at first SSO sign-in and the "Add user" button is replaced by a link to the new-account policy).
- Modify user details (display name and email).
- Send a password invite or reset link by email (the admin never sees or sets passwords; see Password setup by email).
- Delete existing accounts (the user's API keys are deleted too).
- Set the per-user API key policy (see below).
Passwords: admins never see, choose or receive user passwords.
POST /admin/users requires an email and sends an invite link; the response
only says whether it was sent (invite: {sent, expires_at} or {sent: false, error}).
The edit dialog shows the password state and a "Send reset link" / "Resend
invite" button (POST /admin/users/{id}/password-link); the list shows
"Invite pending", "Reset pending" and "Send failed" badges with a mail action.
Without SMTP (Settings → SMTP) a banner links to the SMTP settings, the email
becomes optional and creation or reset generates a temporary password
shown once in a dialog (copy, CSV for batches): the user must change it at first
sign-in before doing anything else ("Temporary password" badge in the list).
The same dialog appears for SSO migration switches, setup links and unlinks.
The user chooses the password on chat-ui /set-password, which
enforces the policy (at least 8 characters, lowercase, uppercase, digit, symbol,
not containing the username; src/data/user_password.py::password_policy_violations).
See Password setup by email.
New accounts (SSO): in the Sign-in tab, with an SSO mode active, the
New accounts section sets who can get an account at first SSO sign-in:
anyone in the organization, only listed emails/domains (one per line,
name@company.com or @company.com) or nobody. Existing accounts are not
affected. See SSO migration.
API key policy: admins do not create API keys; each user creates their own from chat-ui → Settings → API keys. On the user form the admin sets:
| Field | Default | Range |
|---|---|---|
can_create_api_keys | false | Enables the feature for the user |
max_api_keys | 5 | 1–100 active keys |
api_key_max_ttl_days | 90 | 1–3650 days (maximum lifetime of a new key) |
The users list shows an "API key active/max" badge (api_keys_active from
GET /admin/users). Disabling can_create_api_keys immediately revokes all the
user's active keys; lowering the limits only affects new keys. See
API keys.
3. Profile Management
Path: /profiles
Features:
- Create new agent profiles.
- Modify existing profiles (system instructions, description, parameters).
- Export individual profiles to YAML or all in bulk to a ZIP archive.
- Import profiles via YAML files with schema validation.
- Associate MCP servers and enable/disable skills for each profile.
4. Evaluation & Metrics (Agent Telemetry)
Path: /metrics
Features:
- 4 Real-Time KPI Cards & Sparklines: Token consumption (input/output/reasoning breakdown and last turn stats), execution turn durations (average, last turn, P95 latency), total turns & failure rate, and total tool calls & success rate %.
- Granular Temporal Sparklines: Dynamic trendline area and mini-bar charts with local timezone hover tooltips (
1h,6h,24h,7d,30d,all). - Agent Profile Breakdown Table: Per-profile consumption table showing total tokens, input/output/reasoning split, turns, tool calls, success %, and average turn latency.
- User Breakdown & Profile Distribution Table: Expandable user usage view detailing token footprints, turn activity, and per-profile distribution % with specific tool invocation breakdowns.
- Tool & MCP Execution Details: Filterable and searchable table of tool executions across MCP servers with error counts and success rates.
- LLM Model Token Consumption: Visual bar breakdown of prompt vs completion vs reasoning tokens consumed per model.
- MCP Error & Failure Diagnostics: Chronological log of recent MCP errors with server origin, tool name, profile, local timestamp, and full error details.
- Prometheus Dual-Mode Indicator: Real-time badge indicating whether telemetry is being aggregated via Prometheus backend query APIs or via in-process fallback buffers.
5. Skill Management
Path: /skills
Features:
- View registered skills in the system (with usage metrics).
- Create new skills by directly editing Markdown code with YAML frontmatter metadata.
- Promote skills generated from drafts ("draft") to verified ("verified").
- Remove skills (preventing the deletion of those currently in use by active profiles).
6. MCP Hub (unified)
Path: /hub.
Features:
- Install servers from the marketplace and connector catalog.
- Guided wizard: installation → AI analysis → admin review → deployment (see MCP Hub Wizard).
- Configure registry (
command,env,aion_connector_id). - User availability: chat enablement,
credential_mode(none|org_shared|per_user), schema preview from the catalog, application of suggested${AION_USER_*}env. - Advisor: "Ask the assistant" button (
POST /admin/mcp-integrations/advise) ormcp_integration_advisorchat profile. - Probe (
POST /admin/mcp/{slug}/probe): verifies MCP handshake and tool list after install/config.
Post-install checklist (e.g. email):
- Wizard or Edit → correct
credential_mode→ Apply suggested env. - Enable chat for users.
- PROBE on the installed card (≥1 tool, e.g.
search_emails). - Agent profile:
mcp_serversincludes the slug + MCP skill (e.g.email_imap_mcpinconfig/profiles/). - Chat-ui: user credentials if
per_user.
7. Chat privacy (no conversation access)
Admins cannot read users' chats. There is no conversation viewer in the admin UI, and the backend exposes no /admin/* endpoint that returns conversation content.
- Removed:
GET /admin/conversations/global,GET /admin/conversations/{id}/messages,GET /admin/conversations/{id}/render-auditandDELETE /admin/feedback/{message_id}. - Feedback (
GET /admin/feedback?days=7) returns aggregate 👍/👎 counts only, in total, per profile and per model. It never returns message text, comments, prompts, user ids or conversation ids. The dashboard shows these counts in the Feedback · 7 days card. - Scheduled jobs: see the section below. Run outputs and prompts of user-created jobs are never returned.
- Security investigation (
/admin/security/investigate) refuses the data directory (DB, session workspaces),*.db/SQLite files and.env*files.
8. Scheduled Jobs (Scheduled tasks)
Path: /schedules
Features:
- Manage cron jobs for the scheduled sending of prompts to the agent (requires
AION_CRON_ENABLED=1in the backend). - Define cron expressions, time zones, associated profiles, and prompts to execute.
- Bind each job to a dedicated SQL QueryMemory project — required for memory-enabled profiles (the
defaultdrawer is blocked at runtime to prevent cross-project contamination). The selected project is persisted on the job and written into the scheduled-job conversation metadata so the run is scope-bound exactly like a chat-ui turn. - Monitor the outcome of the latest executions and view the history of each run as metadata only (status, timestamps, duration, error messages). Run output, assistant previews and the linked conversation stay private to the job owner.
- For jobs created by users (
created_by != "admin"), the API returns an emptypromptwithprompt_hidden: true. Prompt and profile cannot be changed by admins; schedule, timezone, name, enable/disable and delete still can. - Admins cannot set
session_id: every job runs in its own conversation, never inside an existing user chat. - Enable, disable, or force immediate execution of a job.
9. Memory Management
Path: /memory
Features:
- Manage memory projects: each project groups the shared memory of a team or topic (SQL QueryMemory and Mnemos long-term memory notes).
- Create, edit and delete projects.
- Grant or revoke project access for individual users (members).
10. Logic Extension Hub (Plugins & Hooks)
Path: /plugins
Features:
- Monitor active runtime modules under
data/plugins/. - View the status of the execution pipeline hooks (e.g.
on_user_message,pre_llm_call,on_assistant_message,pre_tool_use). - Perform hot reloading (hot reload) of logical extensions without interrupting the main server process.
11. Audit and Security (Security Audit)
Path: /security
Features:
- Manage security audit logs and static scan reports.
- Initiate AI-driven security analyses (via profiles like "Security Officer") on specific code files.
- View, mark as trusted ("trust") or download detailed reports in JSON or Markdown format.
12. System Health (Infrastructure Integrity)
Path: /system
Features:
- Monitor the integrity of the underlying infrastructure in real time.
- Check the status and URL of the Redis cluster (detecting if the in-process fallback mechanism is active).
- Monitor the unified SQLite database (physical file size and connection string).
- View the active storage backend (local or hybrid) and its root directory for session files.
13. General Settings
Path: /settings
Features:
- Configure global environment variables by writing them directly to the
.envfile via an integrated visual editor. - Automatic parameter validation (e.g. consistency between
AION_CHAT_MAX_TOKENSandAION_THINKING_TOKEN_BUDGETfor Anthropic models). - LLM provider CRUD with connection probe: test endpoint credentials, discover models via
GET /v1/models, pick from list or enter model id manually (admin-ui/lib/llm-probe.ts→POST /admin/llm-providers/probe). - Same probe flow for embeddings and remote OCR (vision server) on the settings form.
- Audio section: like OCR, choose between a remote OpenAI-compatible transcription service (
AION_STT_BASE_URL,AION_STT_API_KEY, model picked via the same connection probe,AION_STT_TIMEOUT/AION_STT_CHUNK_SEClimits) and the on-server engine; in local mode, choose the speech-to-text model (AION_STT_LOCAL_MODEL), the default language (AION_STT_LANGUAGE) and the transcription accuracy (AION_STT_LOCAL_BEAM_SIZE), explained in plain language without showing variable names; models not yet on disk can be downloaded ahead of time (GET /admin/stt/local-models,POST /admin/stt/local-models/{name}/download). See Speech-to-text MCP. - Default provider save syncs
AION_CHAT_MAX_TOKENS/AION_THINKING_TOKEN_BUDGETinto.envand clears the agent cache. - Automatic restart of the Docker container in case of changes (if the environment runs under Docker).
- SMTP (
/settings#smtp): outgoing mail server used for invites, password resets and SSO-migration links (host, port, STARTTLS/SSL/none, credentials, sender, email language) with a "send test email" probe. The SMTP password is write-only and stored encrypted (GET/PUT /admin/smtp,POST /admin/smtp/test).
14. First setup wizard
Path: /first-setup (shown when the backend reports setup incomplete)
Multi-step wizard aligned with /settings and Docker/local .env parity:
| Step | Content |
|---|---|
| LLM | Provider, API key, base URL → Test connection & discover models → model select (or manual id) → token budget validation |
| Embeddings | Service URL + key → probe → embedding model select |
| OCR | Local (PyMuPDF/Tesseract via MCP; clears AION_OCR_*) or Remote vision server → probe → model select |
| Web search | Tavily / other keys |
| Policy | Approval and feature toggles |
| Review | Writes merged keys to .env via settings API |
Probe requires a successful connection test before advancing LLM/embedding/OCR (remote) steps. Shared client helpers: admin-ui/lib/llm-probe.ts; backend: src/runtime/llm_probe.py, src/api/llm_providers.py.
Admin auth (always on)
The FastAPI backend applies a global guard to the /admin/* router
(src/api/admin.py + src/api/admin_agent_db.py):
router = APIRouter(
prefix="/admin",
dependencies=[Depends(require_admin_role)],
)
require_admin_role (in src/api/auth_login.py):
- Resolves identity by calling
require_chat_auth(Bearer / internal BFF secret). API keys never carry theadminrole and are rejected on every/admin/*endpoint (403); see API keys. - Verifies that the token payload contains the
adminrole. - Responds with
401if the token is missing,403if theadminrole is not present.
Override variable (escape hatch in dev):
| Variable | Default | Description |
|---|---|---|
AION_ADMIN_PASSWORD_AUTH | 1 | 0 makes require_admin_role a no-op (opens /admin/*). Do not use in production. |
AION_CHAT_PASSWORD_AUTH | 0 | Independent: the admin remains protected even when the chat is open. |
Login works if at least one of the two auths (chat or admin) is active. The
token issued by POST /auth/login now includes roles (HMAC-signed CSV, no
DB lookup needed per request) and must_change_password:
{
"access_token": "<base64-urlsafe>",
"user_id": "u_admin",
"identifier": "admin",
"roles": ["admin"],
"must_change_password": true
}
User schema: new columns users.roles (TEXT, JSON list) and
users.must_change_password (BOOLEAN). Idempotent migration:
migrations/versions/d1a23b4f0001_user_roles_must_change.py. For existing DBs
already marked as head by Alembic, the columns are added by
src/data/bootstrap.py::_patch_sqlite_columns.
First login & default admin
At setup_aion_env.py (or at the first boot when setup is automatic) the
backend creates a default admin if no user with the admin role is
yet present in the tenant (src/data/user_password.py::admin_exists).
Default credentials:
| Field | Value (env override) |
|---|---|
| Identifier | AION_SETUP_ADMIN_DEFAULT_IDENTIFIER (admin) |
| Password | AION_SETUP_ADMIN_DEFAULT_PASSWORD (admin) |
| Roles | ["admin"] |
| Flag | must_change_password=True |
Disable with AION_SETUP_ADMIN_BOOTSTRAP=0 in .env before setup.
The script prints a conspicuous warning when it creates the admin:
========================================================================
DEFAULT ADMIN CREATED: identifier='admin' password='admin'
At the first login, changing the password will be proposed (skippable 24h).
Disable with AION_SETUP_ADMIN_BOOTSTRAP=0 in the .env before setup.
========================================================================
Change password flow
The must_change_password flag is read by GET /auth/me. On the admin-ui side:
- The
AdminAuthGateautomatically redirects to/change-passwordif the flag istrueand the user has not already "skipped". - The password change page calls
POST /auth/change-passwordwith{old_password, new_password}. The backend revalidates the old password (bcrypt), updates the hash and clears the flag. - "Remind me tomorrow" button → sets
localStorage.aion_admin_change_pw_skipped_until = now + 24h.
On the chat-ui side there is a parallel flow (chat-ui/app/change-password/page.tsx).
Skip key: localStorage.aion_chat_change_pw_skipped_until.
One-click update
When a new release is available the admin-ui shows a banner on every page
(components/VersionUpdateBanner.tsx, fed by GET /admin/version-check).
On GHCR deployments with the aion-updater sidecar it also shows an
Update now button:
components/update/UpdateConfirmDialog.tsxloads the hop plan (GET /admin/update/plan?refresh=true) and lists every release that will be applied, with links to the release notes;- confirming calls
POST /admin/update/start(admin only, audited asupdate.start); components/update/UpdateProgressOverlay.tsx(mounted inAppShell) pollsGET /admin/update/statusevery 3s, shows per-hop progress, the current phase and the log tail, tolerates the 502s caused by the restarts, reloads the page on success and offers Retry (resume from the failed hop) on failure. It also reappears on page load while an upgrade is running.
Without the sidecar the banner only links to the changelog and the manual upgrade guide. See Self-update from the admin-ui.
Next.js Architecture
Why Next.js?
| Reason | Explanation |
|---|---|
| React | Modern UI framework, flexible ecosystem |
| SSR & App Router | Fast rendering and clean management of routes and APIs |
| API routes / BFF | Secure proxying of requests to the FastAPI backend |
| Type safety | Type safety for a complex control panel |
Project structure
admin-ui/
├── app/ # Next.js App Router
│ ├── page.tsx # Home dashboard
│ ├── users/ # User Management
│ ├── profiles/ # Profile Management
│ ├── metrics/ # Evaluation & Agent Metrics
│ ├── skills/ # Skill Management
│ ├── hub/ # MCP Hub (marketplace and wizard)
│ ├── schedules/ # Scheduled Cron Jobs
│ ├── memory/ # Memory projects (QueryMemory + Mnemos)
│ ├── security/ # Security Audit & Scans
│ ├── system/ # Infrastructure integrity (System health)
│ ├── first-setup/ # Initial setup wizard (LLM/embeddings/OCR probe)
│ └── settings/ # General Settings (.env editor + LLM providers)
├── public/ # Static files
│ └── reports/ # Generated security audit reports
└── package.json # Package scripts and dependencies
Configuration
Variables
| Variable | Default | Purpose |
|---|---|---|
NEXT_PUBLIC_AION_API_URL | http://localhost:8001 | FastAPI backend URL |
Development
cd admin-ui
pnpm dev
# Access to the development interface on http://localhost:3870
Production
cd admin-ui
pnpm build
pnpm start
# Access to the interface on http://localhost:3870 or via reverse proxy
Security considerations
Input validation
The Admin UI must validate:
- Profile creation (name uniqueness, validity of associated MCP servers).
- Skill creation (correctness of the frontmatter syntax).
- MCP configurations (security of commands, arguments, and environment).
- Global settings (validation of integers and token budgets).
Audit logging
All administrative operations (user creation, configuration modification, key release) are logged in the audit system to ensure traceability and compliance.
Troubleshooting
"Cannot fetch profiles"
Cause: Incorrect NEXT_PUBLIC_AION_API_URL or backend offline.
Fix:
# Check that the backend is active
curl http://localhost:8001/health
# Verify that the environment variable contains the correct path
echo $NEXT_PUBLIC_AION_API_URL
"403 Forbidden on /admin/*"
Cause: The user has not logged in or does not have the required admin role.
Fix:
- Make sure you have logged in to the
/adminportal with an enabled user. - Verify that the JWT token has not expired.
- In development, if necessary, it is possible to bypass the protection by setting
AION_ADMIN_PASSWORD_AUTH=0in the.envand restarting the FastAPI backend.
"Cannot upload audit report"
Cause: Write permission error on the host's admin-ui/public/reports/ folder.
Fix:
chmod 755 admin-ui/public/reports
chown -R $USER admin-ui/public/reports
Related documents
- REST API - Backend FastAPI endpoints
- Chat UI - Main chat user interface
- Identity and Chat Auth - Authentication and authorization
- Agent profiles - Management and configuration of profiles
- Hermes features - Administrative operations for learning features