# Admin console

Source: https://bulwarkmail.org/docs/guides/admin
Last updated: 2026-11-12

> Manage runtime configuration, sign-in, branding, the user policy, plugins and themes in the admin console.

**Not in Lite.** The admin console is part of Bulwark (not Lite). Lite reads its settings from config.json and policy.json.

The admin console runs inside the same process as the user-facing app. It holds the server and sign-in settings, branding, the user policy, the Organisation pages, plugins, themes, the marketplace, updates, usage stats and the audit log. Each page has its own address under `/admin`.

API keys and app passwords are not here. Each user manages their own under **Settings > Security**; see [Account security](https://bulwarkmail.org/docs/guides/account-security.md).

> **Note.** Bulwark Lite has no admin console and no setup wizard. Its configuration is a `config.json` file next to `index.html`, and an optional `policy.json` for the settings policy. See [static hosting](https://bulwarkmail.org/docs/deployment/static.md).

## First-time setup

The web setup wizard runs on first launch and sets the initial admin password along with JMAP, OAuth, branding, and the session secret. Point a browser at the running container and follow the steps; nothing needs to be in `.env.local` beforehand.

`ADMIN_PASSWORD` in the environment is a bootstrap value for env-driven deployments: it is read only while `admin.json` does not exist yet, then hashed and written there. Once a password exists, change it from the admin console.

### File-based secrets

For Docker / Kubernetes secret mounts, the JSON config supports pointing at a file instead of inlining the secret. Set these keys to the path of a file holding the value: `passwordHashFile` in `admin.json`, the other two in `config.json`. Both files are in `ADMIN_CONFIG_DIR`.

- `passwordHashFile` - admin password hash (alternative to inline `passwordHash`)
- `sessionSecretFile` - session secret (alternative to `SESSION_SECRET` / `SESSION_SECRET_FILE`)
- `oauthClientSecretFile` - OAuth client secret (alternative to `OAUTH_CLIENT_SECRET` / `OAUTH_CLIENT_SECRET_FILE`)

## Admin storage split

Admin data lives in two directories, so the operator-authored config volume can be remounted read-only once the wizard has finished:

```env
ADMIN_CONFIG_DIR=/app/data/admin        # config.json, policy.json, plugins, themes, branding uploads
ADMIN_STATE_DIR=/app/data/admin-state   # audit log, login timestamps, setup token
ADMIN_CONFIG_READONLY=true              # optional: produce clean errors instead of EROFS
```

Unset, they are `./data/admin` and `./data/admin-state`. If you set only `ADMIN_CONFIG_DIR`, state goes to `ADMIN_CONFIG_DIR/state`, so set `ADMIN_STATE_DIR` as well before you mount the config dir read-only. Existing pre-1.6.4 installs using the legacy single `ADMIN_DATA_DIR` continue to work without migration.

```yaml
volumes:
  - bulwark-config:/app/data/admin            # rw during setup
  # - bulwark-config:/app/data/admin:ro       # ro after the wizard completes
  - bulwark-state:/app/data/admin-state       # always rw
```

Without a persistent volume a restart loses `admin.json` and `config.json`. Bulwark then takes the password from `ADMIN_PASSWORD` again. Without that variable there is no admin password, and only a Stalwart administrator can get in, through `STALWART_ADMIN_ACCESS=auto` (see below). If `JMAP_SERVER_URL` isn't set either, the setup wizard runs again with a new token in the logs. Losing the state dir also loses a session secret Bulwark generated, which signs everyone out.

## Signing in

The admin console lives at `/admin` (below the base path if you set one). It uses a separate session from the user app, so you can be signed in as both a regular user and an admin in the same browser.

What a Stalwart administrator account is worth here is configurable, under **Authentication** in the admin console or with `STALWART_ADMIN_ACCESS`:

| Value | Effect |
| --- | --- |
| `auto` (default) | Stalwart admins see the admin shield in the app and are signed into `/admin` without the Bulwark admin password |
| `password` | Stalwart admins see the shield but must enter the Bulwark admin password like everyone else |
| `off` | Stalwart admin status is ignored; `/admin` is reachable only through `/admin/login` with the admin password |

`password` and `off` need an admin password to exist, from the wizard or `ADMIN_PASSWORD`, or the admin console would have no way in.

**Additional admin accounts**, under **Authentication > Admin access**, lists mail accounts that get the same access as Stalwart admin accounts without an admin role in Stalwart, and follow the setting above. Each entry is tied to one configured mail server. The account has to match the name the mail server reports for the signed-in user; upper and lower case of ASCII letters count as the same. The list can only be set in the admin console, not in the environment. Removing an entry doesn't end an admin session that is already open.

Admin sessions are protected with:

- Strict session secret length validation
- Configurable TTL via `ADMIN_SESSION_TTL`
- Configurable trusted-proxy depth via `TRUSTED_PROXY_DEPTH` for accurate client IP attribution
- All admin actions are written to the audit log

## Sections

![The admin console: server details and enabled features, with the section list on the left](https://bulwarkmail.org/_img/light-admin-overview.84e4142a03.1280.webp)

The sidebar starts with Overview, Server, Authentication, Branding and User policy. Under **Organisation** are Domains and groups, Signatures, Templates, Security and Sharing; under **Extensions**, Plugins, Themes and Marketplace; under **System**, Updates, Usage stats and Audit log.

### Overview

Warnings that need attention, the number of accounts, plugins and themes, the running version, the server details (application, storage, JMAP server, last admin login, whether settings sync, OAuth and the Stalwart integration are on) and the latest admin actions. **Storage** says "Local files on this server" for a single instance, or, with [several instances](https://bulwarkmail.org/docs/deployment/multi-instance.md), "Shared store" and how many instances checked in during the last minute.

### Server, Authentication and Branding

Override runtime config without redeploying. These pages write to `ADMIN_CONFIG_DIR/config.json` (same file the setup wizard populates). Most of the keys below are on **Server**; the OAuth, SSO, admin access and framing keys are on **Authentication**, and the images and company details on **Branding**. Admin-managed values fill these keys:

- `appName`
- `jmapServerUrl`, plus the `jmapServers` list for multi-server deployments
- `oauthEnabled`, `oauthOnly`, `oauthClientId`, `oauthIssuerUrl`
- `stalwartFeaturesEnabled`, and separately `stalwartJmapPassthroughEnabled`, the server-side switch for the credential-bearing Stalwart JMAP passthrough. Turn it off to keep the client features but block the passthrough route entirely (env: `STALWART_JMAP_PASSTHROUGH_ENABLED`)
- `stalwartAdminAccess` (see above)
- `settingsSyncEnabled`
- `allowedFrameAncestors`
- `parentOrigin`
- Branding (favicon, app and login logos, login company info)
- Demo mode
- `allowCustomJmapEndpoint`
- `autoSsoEnabled`
- `searchEngineIndexing` - allow search engines to index the webmail. Off by default (emits `noindex`/`nofollow` in the page head); recommended off for private deployments. Env override: `SEARCH_ENGINE_INDEXING`.

Order of precedence: **admin config > env var > legacy build-time fallback > built-in default**. A value saved here wins over the same key in `.env.local`; the admin console shows where each value currently comes from (admin, environment, or default). Changes from the admin console take effect on the next user session without a restart.

### User policy

Which features users get, the push relays they may pick (from your list, rather than typed as a free URL), the default sidebar apps every user gets in addition to the ones they pin themselves, and the settings to lock, hide or preset. These are stored in `policy.json`, not `config.json`. The Organisation pages add per-domain and per-group settings; see [Organisation settings](https://bulwarkmail.org/docs/guides/organisation.md).

![The User policy page in the admin console, with some features switched off and settings locked to a value](https://bulwarkmail.org/_img/light-admin-policy.dcb5b34e07.1280.webp)

**Recipient directory**, on the same page (**Features and settings** in the sidebar), narrows the server accounts people see in the contacts directory, recipient suggestions, sharing, delegation, free/busy and plugins' directory lookups:

- **Own domains only:** shows only accounts in the domains of the signed-in account's addresses, aliases included. Accounts whose name isn't an address are left out.
- **Hidden accounts:** account names (the part before the @), separated by commas, hidden in every domain, such as `noreply`.

In `policy.json` they are `directorySameDomainOnly` and `directoryHiddenLocalparts`. Both change what Bulwark shows, not what Stalwart answers. With directory queries on, any signed-in user can still list all accounts through Stalwart's API.

### Plugins

![The Plugins section of the admin console](https://bulwarkmail.org/_img/light-admin-plugins.2f87f6a3fb.1280.webp)

- Install plugins from the [marketplace](https://bulwarkmail.org/docs/guides/marketplace.md) (the official directory unless `EXTENSION_DIRECTORY_URL` points elsewhere) or upload a ZIP. Plugins installed here are for every user.
- Plugins as a whole are off until you turn on **Plugins** under **Plugin policy**.
- Users can also upload plugins for their own account while **Users may upload plugins** is on (the default). With **Require approval** (also the default) each upload stays off until an admin approves it under **Approval requests**.
- Turn an installed plugin on or off, or open it and turn on **Force on for everyone** so users can't turn it off.
- Settings you save on a plugin's page apply to every user.
- Review each plugin's manifest, declared permissions, `frameOrigins`, and `httpOrigins`.
- Configure a plugin in its inline config panel, without leaving the page.
- Hot-reload and `PLUGIN_DEV_DIR` dev-folder loading for live plugin development (esbuild bundles `src/` on demand).

See [Plugins](https://bulwarkmail.org/docs/guides/plugins.md) for the full architecture.

### Themes

- Upload theme ZIP bundles, or install them from the marketplace, for every user. Users can upload their own themes while **Users may upload themes** is on (the default).
- Turn installed themes on or off, or force one on for everyone.
- Set the default theme and colour mode, lock the colour mode, and hide the themes you don't want users to pick under **Offered to users**.
- Theme API v2, with a token compiler and a skin slot.

### Audit log

Every admin action (sign-in, config and policy changes, plugin and theme changes) is recorded. **Audit log** shows the time, the action, its details (old and new values for config changes) and the client IP (after `TRUSTED_PROXY_DEPTH` resolution).

![The Audit log in the admin console, listing admin actions with their time, details and client IP](https://bulwarkmail.org/_img/light-admin-audit-log.5cc5ae8b52.1280.webp)

### OAuth auto-setup

Where the Stalwart server supports it, a dialog validates the origin and issuer URLs and configures the OAuth client end to end, which gets SSO working without hand-editing config. It is under **Authentication**, **OAuth / OpenID Connect**, as **Set up with Stalwart**. It runs as the Stalwart account signed in to the webmail in the same browser, which needs admin permissions. On Stalwart 1.0.3 and later, or with no account signed in, the dialog asks for a Stalwart admin sign-in instead: a password, an app password or an API key, used for this setup only and not stored.

On Stalwart 1.0, run it once even if you don't use SSO. It gives Bulwark's client the access users who sign in with a two-factor code need for their account security settings: Stalwart's `full` scope (or `security` and `settings` when you aren't a superuser) on 1.0.3 and later, first-party on 1.0.0 to 1.0.2. Everyone who is signed in then has to sign in again. Turn **Enabled** off afterwards if you don't want the SSO button. See [Upgrading to Stalwart 1.0](https://bulwarkmail.org/docs/deployment/updating/stalwart-1-0.md#register-bulwark-with-stalwart).

On Stalwart 1.0 the setup also registers a client for Bulwark Mobile: `bulwark-mobile`, with the same access, no secret and the redirect URI `org.bulwarkmail.mobile:/auth/callback`. The app signs in through it and can then show the account security settings. Without it the app registers a client of its own, which reaches mail, contacts, calendars and files but not those settings. Don't add the app's redirect URI to the `bulwark-webmail` client instead: that client has a secret the app can't send, so its sign-in fails.

### Usage stats

**Usage stats** (under System) shows the exact JSON the next heartbeat would send, turns heartbeats on or off, sends one now while they are on (**Send now**), changes the collector URL and shows when the last one went out. Setting `BULWARK_TELEMETRY` in the environment, to either value, locks the choice and greys out the toggle; no-third-party mode locks it off. See [Anonymous usage stats](https://bulwarkmail.org/docs/features/telemetry.md) for the full schema.

## Behind a reverse proxy

If Bulwark sits behind multiple reverse proxies, set `TRUSTED_PROXY_DEPTH` so audit logs and rate-limiting see the real client IP:

```env
TRUSTED_PROXY_DEPTH=2   # CDN -> ingress -> app
```

## Restricting access

The admin console is part of the running Bulwark process, so it cannot be turned off. Restrict it instead:

- Block `/admin` and `/api/admin` at your reverse proxy and only allow your management network.
- Use a strong admin password and change it from time to time with **Change password** in the console. Changing `ADMIN_PASSWORD` later has no effect once `admin.json` exists.
- Keep it off the public internet in production. A VPN or an IP allowlist is the right gate.

## Troubleshooting

### "Admin password reset on restart"

You haven't mounted a persistent volume for `ADMIN_CONFIG_DIR` (or `ADMIN_DATA_DIR` on legacy installs), so the password hash file is lost on container recreation. Mount the volume and either rerun the setup wizard or (re)set `ADMIN_PASSWORD`.

### "Settings > Security missing"

Account security, API keys and app passwords are user settings, not part of the admin console. They need Stalwart 0.16 or newer, `STALWART_FEATURES` and the JMAP passthrough (`STALWART_JMAP_PASSTHROUGH_ENABLED`) left on (both are on by default), and on Stalwart 1.0 Bulwark 1.18.0 or newer with [OAuth auto-setup](#oauth-auto-setup) run once. Stalwart versions before 0.16 do not expose the JMAP `x:` methods Bulwark uses for self-service management.

### "Admin login fails with correct password"

Check that `SESSION_SECRET` hasn't changed since you last signed in (which would invalidate stored sessions) and that the admin data directory is on a writable filesystem.

## Next step

For the settings an organisation makes for its users, such as signatures, external mail and sign-out times, go on to [Organisation settings](https://bulwarkmail.org/docs/guides/organisation.md).
