Airpost
Background services

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:

PathWhat it is
<profile>/run/engine.sockThe engine protocol (JSON-RPC over NDJSON).
<profile>/run/engine.jsonDiscovery 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.

FlagDescription
--mode, -m <MODE>Required: sync, serve, test, reset, migrate, install-check or import-legacy. Clients use serve: every account in one process.
--detachedServe 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, -oAllow the process to run without a parent bound to stdin.
--verbose, -vLog 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.
--helpPrint usage and exit.

Release builds exit 2 unless the program’s name contains airpost.

Environment

VariableDescription
CONFIG_DIR_PATHThe profile directory. Required.
AIRPOST_ENGINE_KEY_FILEKeep 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.enc in the profile, AES-256-GCM with a key from AIRPOST_ENGINE_KEY_FILE or 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

PathWhat it is
accounts.jsonThe registered accounts, without secrets.
secrets.encThe file secret store, when a key file is used.
airpost.dbThe mail database.
engine.logThe serve engine’s own log (airpost logs engine).
engine-<accountId>.logEach 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.