Profiles and data
The profile directory, the database, what's stored where, secrets and the keychain, logs, and how to back up, restore or move to a new machine.
Everything Airpost keeps on your computer lives in one profile directory, except your passwords and tokens, which live in your OS keychain. Every program uses the same profile by default, so the desktop app, the airpost command, agents and the gateway all see the same mail and settings.
For a short user-facing version, see Data and files.
Where the profile is
| Platform | Location |
|---|---|
| macOS | ~/Library/Application Support/Airpost |
| Linux | ~/.config/Airpost (or $XDG_CONFIG_HOME/Airpost) |
| Linux snap | The snap’s $SNAP_USER_COMMON folder |
| Server image | The profile volume |
The engine reads the profile path from CONFIG_DIR_PATH, and the CLI from --config-dir. Pointing them at another directory gives you a separate, independent profile with its own engine, which is useful for testing. Airpost’s profile is separate from Mailspring’s, so both can run side by side.
What’s inside
| Path | Owner | Contents |
|---|---|---|
airpost.db | Engine | The SQLite database: messages, threads, folders, labels, bodies, the search index, calendars, contacts, tasks and plugin metadata. Runs in WAL mode, so airpost.db-wal and airpost.db-shm sit next to it. |
accounts.json | Engine | Your accounts and their server settings, without secrets. |
settings.json | Engine | Settings the engine and every client share: signatures, templates list, mail rules, undo-send delay, AI and integration options. Rewritten atomically on each change. |
server.json | Engine | The Airpost server connection, when you have one. |
run/ | Engine | engine.sock and the engine.json discovery file. Private to your user. |
engine.log, engine-<accountId>.log | Engine | Logs, below. |
pending-sends/ | Engine | Per-recipient bodies for sends waiting out their undo window. |
secrets.enc | Engine | The encrypted secret store, only when a key file is used. |
config.json | Desktop | Desktop preferences. |
keymap.json | Desktop | Shortcuts you changed. |
templates/ | Desktop | Your templates, one file each. |
packages/ | Desktop | Plugins and themes you installed. |
mcp.json, mcp-token, mcp-audit.log | airpost-mcp | Agent access policy, the HTTP bearer token, and the log of what agents did. See Agents. |
gateway/devices.json | airpost-gateway | Paired browsers, as hashes of their tokens. |
services/ | airpost | Service plugin binaries and their logs. |
No client reads airpost.db directly. They ask the engine, which is why the CLI and agents see the same data the app does and can’t corrupt it.
The database
airpost.db is a cache of what’s on your provider, plus the things only Airpost knows: tasks not yet sent to the server, plugin metadata (snoozes, scheduled sends, reminders), local-only drafts, and draft tombstones. The schema starts from the Mailspring-Sync schema (version 12) and adds Airpost’s migrations, which the engine applies at start.
Because mail is a cache, you can always rebuild it:
| What | Where | Effect |
|---|---|---|
| Rebuild one account | Preferences > Accounts > the account > Rebuild… | Downloads that account’s mail again. |
| Rebuild everything | Preferences > Advanced > Rebuild the mail database | Downloads mail for every account again. Accounts and settings stay. |
| Reset | Preferences > Advanced > Reset Airpost… | Removes all accounts and settings. Mail on your providers isn’t touched. |
A rebuild loses what exists only locally: unsent tasks, local-only drafts, and scheduled sends and snoozes that haven’t synced to an Airpost server. Let pending work finish first.
Secrets
Account passwords, OAuth refresh tokens, integration and AI keys and the Airpost server token are held by the engine as one keyset in one item, so a keychain asks for permission at most once. The airpost-secrets crate has three backends:
The Keychain, as a generic password with the service name Airpost Engine.
There’s no plaintext backend. If none of these is available, the engine can’t store secrets. A keyset that exists but can’t be read (a locked keychain, a wrong key) is an error, never an empty keyset, so a later write can’t wipe your passwords.
Secrets go one way. Clients hand them to the engine (account.add, secrets.set); nothing reads them back over the socket. See Security model.
Logs
| Log | What’s in it |
|---|---|
engine.log | The engine as a whole: start, accounts added and stopped, socket errors. |
engine-<accountId>.log | One account’s sync, tasks and protocol summaries. Rotated to .log.1 up to .log.3. |
launchd-engine.log | macOS only: the engine unit’s stdout and stderr. |
mcp-audit.log | Each agent tool call. |
Only info level and above is recorded. With --verbose IMAP and SMTP traffic is logged too, but authentication payloads never are. airpost logs engine, airpost logs <account> and airpost logs -f read them; Developer > Open Engine Logs opens the folder.
Back up and restore
Your mail is on your provider, so a backup is about the rest: accounts, settings, templates, rules, plugins and anything local-only.
Stop everything
Quit the app. If the background engine is on, run airpost engine stop. Copying the database while the engine writes to it can give you a copy that doesn’t open.
Copy the profile
Copy the whole directory, including airpost.db-wal if it’s there. You can leave out run/ and the logs.
Keep the key separately
With the file store, secrets.enc is useless without its key file. Back up the key somewhere other than the profile backup, or the backup alone is enough to read your credentials.
To restore, stop Airpost, put the directory back, and start it. With the OS keychain on the same computer, nothing else is needed.
Moving to a new computer
Two approaches work:
- Start fresh. Install Airpost and add your accounts again. Mail downloads from your providers. Copy
templates/,packages/andkeymap.jsonover if you want them. - Copy the profile. Copy the stopped profile to the same location on the new computer. Your settings, rules and account list come along. Secrets stored in the OS keychain stay on the old computer, so expect to sign in to each account again. With the file store, copy the key file too.
You can also delete airpost.db on the new machine before the first start to download a clean copy instead of carrying over the cache.
Related
- The engine: the process that writes most of these files.
- Background services: unit files and their logs.
- Self-hosting configuration: volumes on a server.