Admin Console

The admin console is a built-in web UI for managing your Atlas deployment. Access it at /admin in the Atlas web app.

Dashboard

Route: /admin

The dashboard shows deployment health at a glance:

• Connections — Number of registered datasources
• Entities — Tables and views in the semantic layer
• Plugins — Installed plugins and their health status
• Overall health — Aggregated status (healthy, degraded, unhealthy)

Component health checks show live status for each subsystem — Datasource, Internal DB, LLM Provider, Scheduler, and Sandbox — with latency, last-checked timestamp, and model/backend details where applicable.

Connections

Route: /admin/connections

Lists all registered datasource connections with their database type, description, health status, and latency.

Actions:

• Add connection — Create a new datasource with URL, database type, and optional description. For PostgreSQL, an optional schema field is also available. The URL field supports a show/hide toggle for credential safety
• Edit connection — Update an existing connection's URL, type, or description
• Delete connection — Remove a connection (with confirmation dialog). The default connection cannot be deleted
• Test connection — Runs a health check query against the datasource and reports latency and status

Pool Stats

A collapsible Pool Stats section shows real-time connection pool metrics for each datasource:

• Active / Idle / Total connections with a visual bar
• Queries — total queries executed through this pool
• Errors — total errors and consecutive failure count
• Avg time — average query execution time in milliseconds
• Last drain — timestamp of the most recent pool drain

Drain & Recreate — closes all connections in a pool and creates a fresh one. Use this when a connection becomes stale or unresponsive. A 30-second cooldown prevents drain storms.

Pool warmup and auto-drain thresholds are configurable via ATLAS_POOL_WARMUP and ATLAS_POOL_DRAIN_THRESHOLD

Semantic Layer Browser

Route: /admin/semantic

A two-panel browser for exploring the semantic layer:

• Left sidebar — File tree showing entities, metrics, glossary, and catalog
• Right panel — Detail view with a Pretty / YAML toggle

In Pretty mode, entities show parsed dimensions, joins, measures, and query patterns with formatted tables. In YAML mode, the raw YAML source is displayed with syntax highlighting.

Browse entities by clicking them in the sidebar. The catalog shows use_for tags and common_questions. The glossary highlights ambiguous terms. Metrics display SQL, aggregation type, and objectives.

In SaaS mode, admins can create, edit, and delete entities directly from the UI with schema-aware autocomplete and full version history. See Semantic Editor for the full guide.

See Semantic Layer for the YAML format reference.

Schema Diff

Route: /admin/schema-diff

Compares the live database schema against the semantic layer YAML files to detect drift:

• Summary cards — New tables (in DB, not in YAML), removed tables (in YAML, not in DB), changed tables (column-level drift), unchanged tables (in sync)
• New tables — Green cards listing tables that exist in the database but have no corresponding entity YAML. Shows a suggestion to run atlas init --update
• Removed tables — Red cards listing entity YAMLs that reference tables no longer in the database. Indicates stale entities that should be cleaned up
• Changed tables — Amber expandable cards with a column-level diff table showing added columns, removed columns, and type mismatches between DB and YAML
• In-sync state — When no drift is detected, shows a green success message

Multiple connections: If multiple datasource connections are registered, a connection selector dropdown appears in the page header. The diff is re-computed when you switch connections.

API endpoint: GET /api/v1/admin/semantic/diff?connection=<id> — returns structured JSON with newTables, removedTables, tableDiffs, unchangedCount, and a summary object.

Audit Log

Route: /admin/audit

Two tabs: Log and Analytics.

Log

Shows every SQL query executed by the agent with:

• Stats — Total queries, total errors, error rate
• Log table — Timestamp, user, SQL query, tables accessed, duration, row count, success/failure

Data classification tags: Each audit entry includes tables_accessed and columns_accessed arrays extracted from the validated SQL AST. These enable compliance-grade filtering — answer questions like "which queries touched the users table?" without parsing SQL text.

Filters:

• Table — Filter by table name (dropdown populated from audit data). Uses JSONB array matching on the tables_accessed column
• Column — Filter by column name (dropdown populated from audit data). Uses JSONB array matching on the columns_accessed column
• Date range (from/to)
• Connection
• Status (success/error)
• Free-text search (SQL, user, error)
• Pagination

Analytics

Charts and tables for query performance insights:

• Query volume — Line chart showing queries and errors per day over the selected date range
• Slowest queries — Top 20 queries ranked by average duration, with max duration and execution count
• Most frequent queries — Top 20 queries ranked by execution count, with average duration and error count
• Error breakdown — Bar chart grouping errors by message pattern
• Per-user activity — Table showing query count, average duration, and error rate per user

Actions

Route: /admin/actions

Lists action log entries with status filtering:

• Tabs — Pending, Executed, Denied, Failed, All
• Table — Relative timestamps (hover for absolute), action type with icon badge, target, summary, status badge
• Expandable rows — Full payload, timestamps, error details, and a link to the originating conversation (when available)
• Empty states — Context-aware messages per filter tab

Actions:

• Approve / Deny individual pending actions
• Bulk approve / deny — Select multiple pending actions with checkboxes and approve or deny them in one operation. A "select all" toggle selects every pending action in the current view

See Actions Framework for details on approval modes.

Scheduled Tasks

Route: /admin/scheduled-tasks

Manages recurring queries:

• Filter tabs — All, Enabled, Disabled
• Table — Name, question, cron expression, delivery channel, next run time, enabled status
• Expandable rows — Recent run history with status, timing, and token usage

Actions:

• Create task — Form dialog with task name, natural language question, cron schedule (presets or custom expression with human-readable preview and next-run times), delivery channel (email, Slack, webhook), approval mode, and connection selector
• Edit task — Same form, pre-populated with existing values
• Toggle enabled/disabled
• Run now — Trigger immediate execution

Run History

Route: /admin/scheduled-tasks/runs

Cross-task run history page showing all executions across all tasks (newest first).

• Filters — Task name, status (running, success, failed, skipped), date range
• Table — Task name, status badge, started timestamp, duration, token usage, error preview
• Expandable detail — Full error message, timestamps, duration, token usage, links to conversation (and action, when applicable)

See Scheduled Tasks for setup and configuration.

Token Usage

Route: /admin/token-usage

Tracks LLM token consumption across all agent interactions:

• Summary cards — Total tokens, prompt tokens, completion tokens, total requests (with per-request averages)
• Token usage over time — Area chart showing prompt and completion tokens per day
• Top users — Table ranking users by total token consumption with prompt/completion breakdown

Filters:

• Date range (from/to) — defaults to last 30 days

Token data is recorded automatically for every agent interaction (chat and query endpoints). When no internal database is configured, token usage is logged via pino only.

Plugins

Route: /admin/plugins

Manage installed plugins — enable/disable, health checks, and configuration.

In SaaS mode, the page includes a tabbed interface with Installed and Available tabs, providing a full plugin marketplace for browsing, installing, configuring, and uninstalling plugins. See Plugin Marketplace for the full guide.

In self-hosted mode, the page shows config-loaded plugins with:

• Plugin cards — Each card shows name, type(s), version, health status, and enabled state
• Health check — Trigger a live health probe for any plugin
• Enable/disable toggle — Toggle a plugin on or off without restarting. Disabled plugins are skipped during agent execution (queries, hooks, tool registration)
• Configure — Opens a config dialog with form inputs generated from the plugin's config schema. Secret values (API keys, tokens) are masked in the UI

How it works:

• Toggling a plugin immediately takes effect — disabled plugins are excluded from getByType() and getAllHealthy() calls in the agent loop
• Config changes are saved to the plugin_settings table and take effect on next restart
• Plugins that implement getConfigSchema() expose a typed form in the UI. Plugins without it show current config as read-only JSON

Settings

Route: /admin/settings

Manage application configuration from the UI. Settings follow a three-tier resolution: DB override > env var > default.

• Grouped sections — Query Limits, Rate Limiting, Security, Sessions, Sandbox, Platform, Agent, Appearance, Secrets
• Source badges — Each setting shows where its current value comes from:
  • override (blue) — value saved in the internal database
  • workspace-override (purple) — value saved per-workspace
  • env (green) — value from an environment variable
  • default (gray) — built-in default
• Edit — Override any non-secret setting. Changes are saved to the internal database
• Live vs Restart — Each setting shows whether changes take effect immediately (Live) or require a server restart (Requires restart). Query Limits, Rate Limiting, Sessions, Sandbox, and Appearance are live; Security, Platform, and Agent settings require a restart
• Reset — Remove a DB override to revert to the environment variable or default value
• Secrets — Sensitive settings (API keys, database URLs) are masked and read-only. Manage these via environment variables
• SaaS mode — Workspace admins only see settings marked as workspace-visible. Platform admins see all settings. The response includes a deployMode field and a manageable flag indicating whether settings can be persisted

Available settings:

Learned Patterns

Route: /admin/learned-patterns

Review, approve, and manage query patterns the agent has learned:

• Stats — Total patterns, pending review, approved, rejected
• Status filter — Tabs to filter by All / Pending / Approved / Rejected
• Entity filter — Dropdown to filter by source entity (table)
• Pattern table — Status badge, SQL pattern (monospace, truncated), description, source entity, confidence (progress bar), repetition count, source (Agent or CLI), created date

Detail sheet — Click any row to open a side panel with:

• Full SQL pattern in a monospace block
• Metadata (entity, source, confidence, repetitions, timestamps)
• Review history (who reviewed, when)
• Source queries that originated the pattern

Actions (per pattern):

• Approve — Mark a pattern as approved
• Reject — Mark a pattern as rejected
• Delete — Permanently remove a pattern (with confirmation dialog)

Bulk actions:

• Select multiple patterns with checkboxes
• Approve selected / Reject selected — Update all selected patterns at once (max 100 per operation)

All status changes record the reviewer and timestamp. Approve/reject use optimistic UI updates — the table updates immediately, reverting on failure.

Prompt Library

Route: /admin/prompts

Manage curated prompt collections — pre-written questions organized by industry that help users get started with common analyses.

Built-in Collections

Atlas seeds three built-in collections on first boot:

• SaaS Metrics — MRR, churn, LTV, CAC, ARPU, and growth indicators
• E-commerce KPIs — GMV, AOV, conversion rates, inventory, and fulfillment metrics
• Cybersecurity Compliance — vulnerability tracking, incident response, and compliance scores

Built-in collections are read-only and visible to all users.

Custom Collections

Admins can create custom prompt collections scoped to their organization:

1. Click Create Collection and fill in the name, industry, and description
2. Add prompt items with questions, descriptions, and categories
3. Reorder items within a collection
4. Custom collections are only visible to members of the admin's organization

Chat Integration

Users can access the prompt library from the chat interface via the book icon in the header. Clicking a prompt immediately sends it as a question.

Cache

Route: /admin/cache

Displays query result cache statistics and provides a manual flush control:

• Hit Rate — Cache hit percentage with a visual progress bar, plus hit and miss counts
• Storage — Current entry count vs max size, fill percentage, and TTL
• Flush Cache — Removes all cached entries with a confirmation dialog. After flushing, subsequent queries hit the database directly until the cache repopulates

API endpoints:

Sessions

Route: /admin/sessions

Manage active user sessions across all users:

• Stats — Total sessions, active sessions, unique users
• Search — Filter by email or IP address
• Session table — User, created time, last active, IP address, user agent

Actions:

• Revoke session — Immediately invalidate a specific session (user gets 401 on next request)
• Revoke all for user — Force logout a user across all devices
• Bulk revoke — Select multiple sessions and revoke them at once

Session Timeouts

Configure automatic session timeout policies via environment variables or atlas.config.ts:

// atlas.config.ts
export default defineConfig({
  session: {
    idleTimeout: 3600,       // 1 hour idle timeout
    absoluteTimeout: 86400,  // 24 hour absolute timeout
  },
});

These can also be changed at runtime via Admin > Settings without a server restart.

User Self-Service

Non-admin users can manage their own sessions via GET /api/v1/sessions and DELETE /api/v1/sessions/:id. Users can only see and revoke their own sessions.

User Management

Route: /admin/users

Full user management with stats and controls:

• Stats — Total users, admins, analysts, viewers
• Search — Filter by email
• Role filter — Filter by role

Actions (per user):

• Change role — Set to viewer, analyst, or admin
• Ban/unban — Temporarily or permanently ban a user
• Revoke sessions — Force logout across all devices
• Delete — Permanently remove user and sessions

Invite users:

• Invite user button opens a dialog with email input and role selector
• If RESEND_API_KEY is configured, an invitation email is sent automatically
• If no email delivery is configured, the dialog shows a one-time invite link to copy and share manually
• Invited users are assigned the selected role automatically on signup
• Pending invitations section shows outstanding invitations with status (pending, accepted, expired, revoked) and expiry date
• Admins can revoke pending invitations

Safety guards:

• Cannot change your own role
• Cannot ban or delete yourself
• Cannot demote or delete the last admin

Workspace Management

Route: /admin/organizations

Manage workspaces (organizations) across the platform:

• Organization list — Name, slug, status badge (active/suspended/deleted), plan tier, member count, creation date
• Detail view — Members with roles, pending invitations, creation date, and metadata
• Stats — Member count, conversation count, query count per organization

Workspace Status

Actions

• Suspend — Block all queries for a workspace. Drains the org's connection pools immediately. Use this for billing holds, abuse prevention, or maintenance windows
• Activate — Reactivate a suspended workspace. Queries resume immediately
• Delete — Soft-delete with cascading cleanup: drain pools, flush caches, cascade database cleanup, mark as deleted. This is not reversible from the UI
• Change plan — Set a workspace's plan tier: free, team, or enterprise

Health Status

The organization status endpoint (GET /admin/organizations/:id/status) returns workspace health metrics:

• Members — Total member count
• Conversations — Total conversations
• Queries last 24h — Recent query volume
• Connections — Registered datasource count
• Scheduled tasks — Active task count
• Pool metrics — Connection pool stats (if org-scoped pooling is enabled)

Admin API

See Usage Metering for per-workspace usage tracking.

API Keys

Route: /admin/api-keys

Create and manage API keys for programmatic access via the SDK, MCP server, or embeddable widget. Keys are shown once at creation and cannot be retrieved later.

See API Key Management for the full guide.

Integrations

Route: /admin/integrations

Connect and manage external platform integrations — Slack, Microsoft Teams, Discord, Telegram, and webhooks — from a single page. Each integration shows its connection status and provides connect/disconnect actions.

See Integrations Hub for the full guide.

Sandbox / Execution Environment

Route: /admin/sandbox

In self-hosted mode, configure which sandbox backend the explore and Python tools use via a dropdown selector. In SaaS mode, the page shows an integration card grid where workspace admins connect their own cloud sandbox providers (Vercel, E2B, Daytona) alongside the managed Atlas Cloud Sandbox.

See Sandbox Configuration for the full guide.

Data Residency

Route: /admin/residency

Control where your workspace data is stored and request region migrations.

Viewing Your Region

When a region is assigned, the page displays:

• Current region — Name, region ID, and compliance badge (e.g. "GDPR compliant" for EU regions, "SOC 2 compliant" for US regions)
• Assignment date — When the region was first assigned
• Status — Active badge confirming the region is serving traffic

Requesting a Region Migration

To migrate to a different region:

1. Click Change Region on the Data Region card
2. Select the target region from the available options — your current region is shown for reference
3. Review the migration summary (current region → target region with compliance badges)
4. Click Request Migration, then confirm in the confirmation dialog

Migration Phases

Once submitted, a migration progresses through these phases:

What to Expect During Migration

• A status banner at the top of the page shows real-time migration progress
• Pending migrations can be cancelled before processing begins
• Failed migrations can be retried with a single click
• Only one migration can be active at a time — the "Change Region" button is disabled while a migration is pending or in progress
• After completion, the Data Region card updates to reflect the new region

Residency Admin API

Custom Domain

Route: /admin/custom-domain

Serve Atlas from your own domain (e.g. data.acme.com) with automatic TLS certificate provisioning.

Adding a Custom Domain

1. Navigate to Admin Console → Custom Domain
2. Enter your desired subdomain (e.g. data.acme.com) — use a subdomain, not a root domain
3. Click Add Domain

Atlas generates a CNAME target that you need to configure in your DNS provider.

DNS Verification

After adding a domain, a DNS configuration card appears with the required CNAME record:

Add this record to your DNS provider (Cloudflare, Route 53, Google Cloud DNS, etc.). DNS propagation may take up to 48 hours.

Checking Verification Status

Click Check Status to trigger a verification check. The domain progresses through these statuses:

Removing a Domain

Click Remove Domain and confirm in the dialog. This immediately stops serving traffic on the custom domain. The action cannot be undone — you would need to add and verify the domain again.

Domain Admin API

API Endpoints

All admin endpoints are at /api/v1/admin/ and require the admin role. See the SDK for typed client methods.

Troubleshooting

Admin page shows "not enabled" message

Cause: The feature requires a dependency that isn't configured — Audit Log and Token Usage need DATABASE_URL, Actions needs ATLAS_ACTIONS_ENABLED=true, Scheduled Tasks needs ATLAS_SCHEDULER_ENABLED=true.

Fix: Set the required environment variable and restart the server. The feature gate message on each page tells you exactly what's missing.

Cannot access /admin — 403 or redirect to login

Cause: Your user account doesn't have the admin role, or authentication isn't configured.

Fix: In managed auth, have an existing admin promote your account via Admin > Users. In BYOT mode, ensure your JWT includes the correct role claim. In none auth mode, all users have implicit admin access.

Settings changes don't take effect

Cause: Some settings (Security, Agent) require a server restart, while others (Query Limits, Rate Limiting) apply immediately. The settings page shows a Live or Requires restart badge on each setting.

Fix: Check the badge next to the setting you changed. If it says Requires restart, restart the Atlas server for the change to apply. On app.useatlas.dev (SaaS mode), most settings are picked up on the next request without a restart — though infrastructure settings like LLM provider and model may require redeployment.

For more, see Troubleshooting.

See Also

• Authentication — Set up managed auth (required for multi-user admin)
• Multi-Datasource Routing — Configure and monitor multiple datasource connections
• SDK Reference — Programmatic access to admin endpoints
• Scheduled Tasks — Configure recurring queries managed via the admin console
• Actions — Approval-gated write operations visible in the admin console
• API Key Management — Create and manage API keys
• Integrations Hub — Connect Slack, Teams, and webhooks
• Sandbox Configuration — Configure sandbox backends
• Semantic Editor — Create and edit entities from the UI
• Plugin Marketplace — Browse and install plugins
• Self-Serve Signup — Region selection during onboarding
• White-Labeling — Custom branding for your workspace