Run the admin console
Create the first administrator, finish the setup checklist, find your way around the sidebar, and use plugins, caching and the audit log from /admin.
The admin console at /admin is where operators run the product. Use this guide once, right after installation, and come back to it when you tune caching or review the audit log.
Before you begin
- A migrated database (
pnpm db:migrate). - A shell on a machine that can reach that database.
- The email address and password you want for the first administrator.
Create the first administrator
Nobody can open /admin until one user holds the admin.access permission, and permissions are granted inside the console. The bootstrap script creates the first administrator from the command line.
Add the administrator to .env
SUPER_ADMIN_EMAIL=you@example.com
SUPER_ADMIN_PASSWORD=at-least-8-characters
SUPER_ADMIN_NAME="Super Admin"SUPER_ADMIN_EMAIL and SUPER_ADMIN_PASSWORD are required. The password must be at least 8 characters and is only used when the account is created. SUPER_ADMIN_NAME is optional and defaults to Super Admin.
Run the bootstrap script
pnpm db:bootstrap-super-adminThe script creates the account with a verified email, or promotes an existing account with that email without changing its password. It sets the access status to Active, writes every permission the template ships, grants them all to a Super Admin role and assigns that role. It also writes the baseline email templates, marketing pages and rate-limit rules.
Remove the password and sign in
Delete SUPER_ADMIN_PASSWORD from .env. Only the script reads these variables. Sign in at /auth/sign-in and open /admin.
Run the script again after an upgrade or a module install that adds permissions, so the Super Admin role receives them.
Work through the setup checklist
Open Setup
Open Setup from the workspace sidebar (/setup). It reads the live configuration on every load.
Fix each item marked Not ready
Every item states what is missing and has a Configure button that opens the page that fixes it.
Required items are Session secret, Sign-in method, Email delivery and Scheduled jobs. Payment provider, Object storage, AI channels, Newsletter provider (with the newsletter module) and Analytics provider are optional. The badge reads Nothing required is missing when every required item is ready.
Two required items are not set in the console. Session secret is BETTER_AUTH_SECRET in the environment, because it is needed before the database is read; see Manage configuration. Scheduled jobs reports whether the once-a-minute background round is running. It has no Configure button, and its message names the platform switch to check. See Troubleshoot a project.
Find your way around the sidebar
The sidebar is grouped, and every entry is hidden from a user who lacks its permission.
| Group | Entries |
|---|---|
| Overview | Dashboard (/admin), Users, Countries |
| Operations | Roles, Permissions, Support |
| Commerce | Plans (/admin/plans), Orders, Subscriptions |
| Platform | AI Tasks, Chats, API Keys, Rate Limits, Assets |
| Content | CMS, Waitlist and Affiliates, each with its module |
| Security | Webhooks, Audit |
| Settings | Auth, Payment, Storage, AI, Analytics and Email Config, Email, Notifications, Plugins (/admin/plugins), plus Sandbox, Search and Image Agent settings with the agent modules |
Plans is where you create the pricing plans that /pricing lists and checkout charges. It needs plans.read, and plans.write to save. See Pricing plans.
Switch a plugin on or off
- Open Settings → Plugins (
/admin/plugins, needsconfig.read). It lists every plugin installed in this build with what it contributes. - Use the switch on a module's row; saving needs
config.write. The builtin foundation plugin is always on.
A disabled plugin's console entries disappear and its /admin and /app pages return not found. Its data stays. This page does not install plugins; a plugin is installed by adding it to src/plugins/installed.ts. See Console plugins.
Tune caching
Open the cache settings
Open /admin/config/cache. It has no sidebar entry; saving needs config.write.
Set each area
For each area, tick Enabled, set Time to live (seconds) and choose a Backend available in this runtime. Click Save.
Clear a cache when needed
Clear this domain empties that area's cache immediately.
Review the audit log
Open Security → Audit (/admin/audit, needs audit.read). It lists the latest 500 events, such as user status changes, auth and provider settings saves, API key events and rate-limit decisions, and offers them as a CSV download.
Before setup
Without the bootstrap script no one can open the console. A signed-in user without admin.access is sent to /system/permission-denied, and a visitor without a session to /system/session-expired.
Verify
- Sign in as the administrator:
/adminopens and the sidebar shows every group. /setupshows Nothing required is missing once the required items are ready.- In the repository, run:
pnpm validate:users
pnpm validate:auth-boundaryTroubleshooting
SUPER_ADMIN_EMAIL is required.
The script found no value. Add both variables to .env, or pass them inline: SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin.
A page shows Permission denied: <permission>
The user can open the console but lacks the permission that page checks. The dashboard at /admin alone needs admin.dashboard.read, users.read, credits.read and ai.read. See Manage users, roles and permissions.
A new permission does not reach the Super Admin
Role permissions are written when pnpm db:bootstrap-super-admin runs. Run it again.
A sidebar entry is missing
The sidebar hides entries the user has no permission for. Give the user a role that carries the permission for that page; see Roles and permissions.