The engine
What airpost-engine does, where its socket lives, and how to run it after the app quits.
airpost-engine is the Rust sync engine. It is the only process that touches mail: it holds your IMAP, SMTP and OAuth credentials, the mail database, bodies, attachments and search, and it runs sync, sending, send later, snooze, reminders and mail rules. One process holds all your accounts.
Every client is a separate program that talks to the engine over a local socket: the desktop app, airpost, airpost-mcp and airpost-gateway. No client reads the database directly. For the design behind this, see Architecture.
The socket
A serve engine listens on a Unix socket in the profile and writes a discovery file next to it:
| Path | What it is |
|---|---|
<profile>/run/engine.sock | The engine protocol (JSON-RPC over NDJSON). |
<profile>/run/engine.json | Discovery file: the engine’s pid, socket and accounts, and detached: true for a detached engine. Rewritten when an account is added or removed. |
The run/ directory is private to your user, and the engine only takes connections from the same user (peer uid check). Every local connection acts as you. Remote clients reach the engine only through the gateway; see Self-hosting.
airpost finds engines by reading the discovery files in <profile>/run/. If none is live, it exits 3.
How clients find it
A client that finds no live engine stops there. airpost prints this and exits 3:
airpost: no engine running: start Airpost, or check --config-dir or AIRPOST_CONFIG_DIR (looked in /Users/you/Library/Application Support/Airpost/run)
The engine announces features in its hello. A client that needs one the engine lacks says so and asks you to update Airpost, rather than failing in the middle of a command.
Running after the app quits
The desktop app starts its own engine when none is running. To keep one running after you quit the app, at login, or on a machine with no desktop, install it as a user unit:
airpost engine install
The unit runs airpost-engine --mode serve --detached with the profile in CONFIG_DIR_PATH, starts at login and restarts after a failed exit. While the desktop’s own engine is running, install only enables the unit; it starts when you run airpost engine start after quitting the app or at your next login, and the app joins it at launch. In the desktop app the same thing is Preferences > General > Keep Airpost running in the background.
Commands, flags, unit files and logs are in Background services.
The engine isn’t socket-activated. It syncs mail with no client connected, so it has to be running already.
Running it by hand
You normally don’t run airpost-engine directly. For debugging, a detached serve engine on a test profile:
CONFIG_DIR_PATH=/tmp/airpost-test airpost-engine --mode serve --detached
airpost --config-dir /tmp/airpost-test status
CONFIG_DIR_PATH is required; without it the engine prints its usage and exits.
| Flag | Description |
|---|---|
--mode, -m <MODE> | Required: sync, serve, test, reset, migrate, install-check or import-legacy. Clients use serve: every account in one process. |
--detached | Serve mode: run without a parent process; the socket takes the parent’s methods from local connections. |
--socket <PATH> | Sync and serve modes: serve the engine protocol on this Unix socket path instead of <profile>/run/engine.sock. |
--orphan, -o | Allow the process to run without a parent bound to stdin. |
--verbose, -v | Log all IMAP and SMTP traffic. AUTH payloads are never logged. |
--account, -a <JSON> | Account JSON with credentials (sync and other single-account modes). |
--identity, -i <JSON> | Identity JSON, or null. |
--help | Print usage and exit. |
Release builds exit 2 unless the program’s name contains airpost.
Environment
| Variable | Description |
|---|---|
CONFIG_DIR_PATH | The profile directory. Required. |
AIRPOST_ENGINE_KEY_FILE | Keep secrets in <profile>/secrets.enc, sealed with the key in this file, instead of the OS keychain. The engine creates the key file if it doesn’t exist. airpost engine install --key-file sets it in the unit. |
The CLI looks for the engine binary beside airpost, or at AIRPOST_ENGINE_BIN when set.
Secrets
Passwords, refresh tokens, integration keys and the Airpost server token are held as one keyset in one of:
- the macOS Keychain (service
Airpost Engine), - the Linux Secret Service,
secrets.encin the profile, AES-256-GCM with a key fromAIRPOST_ENGINE_KEY_FILEor systemd’s$CREDENTIALS_DIRECTORY.
There is no plaintext backend. On a server without a keyring, use a key file:
airpost engine install --key-file ~/.config/airpost-engine.key
loginctl enable-linger "$USER"
A key file keeps credentials out of a leaked profile. It doesn’t protect against root on the host, or against another process running as you, which can act through the socket.
Files in the profile
| Path | What it is |
|---|---|
accounts.json | The registered accounts, without secrets. |
secrets.enc | The file secret store, when a key file is used. |
airpost.db | The mail database. |
engine.log | The serve engine’s own log (airpost logs engine). |
engine-<accountId>.log | Each account’s log (airpost logs <account>), rotated to .log.1 up to .log.3. |
run/ | The socket and discovery files. |
Default profile locations are in the CLI overview. See also Data and files.
Upgrading
After replacing the binary (a package upgrade, or running the install script again), restart the unit so it runs the new one:
airpost engine restart
With Homebrew, run airpost engine install first, then airpost engine restart.
Checking on it
airpost status # engines, accounts, services
airpost logs engine -f # the engine's own log
airpost logs you@gmail.com -n 200
airpost rpc engine.status # the raw status document
Troubleshooting
Related: Background services, CLI overview, Architecture.