imbox has two kinds of settings. Environment settings belong to the server and are set once, in a file. App settings belong to you and are changed in the browser under Settings.
Environment settings
Where they live
| Install | File | Apply a change |
|---|---|---|
| Server script | /etc/imbox/imbox.env | sudo systemctl restart imbox |
| Docker Compose | .env next to docker-compose.yml | docker compose up -d |
| Railway | The service's Variables tab | Railway redeploys |
Docker passes on a short list
docker-compose.yml hands only these to the app: APP_URL, SESSION_SECRET, APP_NAME, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, MS_CLIENT_ID, MS_CLIENT_SECRET and RESEND_API_KEY, plus the database address it builds from POSTGRES_PASSWORD. For any other setting below, add a line for it under environment: in docker-compose.yml, for example WEB_CONCURRENCY: 2.
You must set
The install sets these for you. They are here so you know what they do.
| Setting | What it is |
|---|---|
APP_URL | The public address, with https://, for example https://imbox.example.com. It must match the address in your browser. imbox checks it on every change request, and uses it for sign-in redirects and links. |
SESSION_SECRET | A random value from openssl rand -hex 32. It signs the session cookie and encrypts mailbox passwords, AI keys, app secrets and two-factor secrets. See Security. Never change it once mail is connected. Keep a copy off the server. |
DATABASE_URL | The PostgreSQL address, for example postgres://imbox:[email protected]:5432/inbox. |
Sign-in with Google and Microsoft, and sending from domains
All optional. They can also be set and changed without a restart under Settings → Accounts → Provider credentials. If the same value is set in the environment, the environment wins.
| Setting | What it is |
|---|---|
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | Your Google OAuth client, for Connect Gmail and Google Calendar. See Mailboxes. |
MS_CLIENT_ID, MS_CLIENT_SECRET | Your Microsoft Entra app, for Outlook and Microsoft 365. See Mailboxes. |
RESEND_API_KEY | A Resend key, for sending from domain mailboxes. |
INBOUND_SECRET | A secret that switches on the inbound mail webhook, POST /inbound/mail, used by domain mailboxes. |
Server and tuning
| Setting | Default | What it does |
|---|---|---|
HOST | 127.0.0.1 | The address the app listens on. Keep it local and put the proxy in front. The Docker image listens on all addresses inside its container. |
PORT | 8787 | The port it listens on. |
APP_NAME | imbox | The name shown on the sign-in page and in the browser tab. |
WEB_CONCURRENCY | 1 | How many web processes to run. See a busier server. |
PG_POOL_MAX | 10 | Database connections per process. |
PG_STATEMENT_TIMEOUT_MS | 20000 | Stops a database query after this many milliseconds. 0 turns it off. |
PG_CONNECT_WAIT_MS | 10000 | How long a request waits for a free database connection. |
LISTEN_DATABASE_URL | none | A direct database address for live events, when DATABASE_URL goes through a pooler. |
CRON_SECONDS | 60 | How often mail is checked and scheduled sends go out. 0 turns the timer off. |
EGRESS_ALLOW_HOSTS | none | Comma-separated host names the app may reach even if they resolve to a private address, for example ollama for a local model. |
ALLOW_PRIVATE_EGRESS | 0 | 1 lets the app reach private addresses everywhere. Leave it off unless you know why you need it. |
App settings
These are changed in the browser and stored in the database, so they are part of your backup.
| Settings Section | Configurable Options |
|---|---|
| Preferences | Dark/light theme, keyboard navigation, desktop notifications, remote image loading policies, version check switch, and away mode settings. |
| Accounts | Connect/disconnect IMAP, Gmail, and Outlook accounts; re-sync mail history; signatures; OAuth provider keys. |
| Domains | Custom domain configuration, Stalwart server connection, domain mailbox routing. |
| Integrations | Browser extension token management (imx_...), revocation, and access logs. |
| Calendar | Google Calendar sync toggles, subscribed .ics webcal feeds, mailbox calendar colors. |
| AI | Model provider (Anthropic, OpenAI, xAI, Gemini, Ollama, custom), model name, API key, memory inspection, and automated feature switches. |
| Security | Password change, Two-Factor Authentication (TOTP), passkeys (WebAuthn), and active session termination. |
Next
- Mailboxes: the Google and Microsoft setup these credentials belong to.
- Self-hosting: when to raise
WEB_CONCURRENCY. - Backups and restore: your
SESSION_SECRETgoes with them.