The engine
One process for all your accounts, the local socket clients attach to, detached mode, and the engine's lifecycle.
airpost-engine is the program that does all of Airpost’s mail work. It syncs your accounts, holds their credentials, owns the database and search index, and runs every change you make. The desktop app, the airpost command, airpost-mcp and airpost-gateway are clients of it: they don’t open the database or talk to your mail server themselves.
This page explains how the engine is organised and how clients attach. For commands and flags, see The engine in the CLI tab.
One process, all accounts
Clients use the engine in serve mode (airpost-engine --mode serve). It starts with no account, binds its socket, and then runs every account you add in the same process.
Each account runs in its own runtime with its own threads, its own stream of changes and its own log file, engine-<accountId>.log. The main threads of an account are:
| Thread | What it does |
|---|---|
main | Runs the local phase of tasks you queue and answers account-scoped requests. |
background | Lists folders and labels, scans folders for changes, and sweeps messages that disappeared from the server. |
foreground | Holds IMAP IDLE on the inbox, fetches bodies, runs the remote phase of tasks, and pushes drafts. |
calContacts | Syncs calendars and contacts on a fixed schedule. |
metadataExpiration | Fires snoozes, scheduled sends and reminders when they come due. |
mailRules | Applies your mail rules to arriving mail. |
metadata | Pulls plugin metadata from an Airpost server. Only started when one is connected. |
Engine-wide threads handle the socket, stdin and signals, and a liveQueries thread keeps clients’ live queries up to date.
When an account fails
A failure on one of an account’s threads (a non-retryable error, a database error while applying a task, or a crash) stops that account alone. The engine sends account.state with stopped and the error to every client, and the other accounts keep syncing.
What happens next depends on why it stopped:
- Refused credentials. The account stays stopped with
authFaileduntil you sign in again. - Anything else. The engine starts it again after a backoff and reports when (
retryAt). Five stops within five minutes stop it for good, until it’s added again.
A crash on an engine-wide thread (the socket, stdin or signals) ends the whole process.
The socket
The engine listens on a Unix domain socket and writes a discovery file next to it:
| Path | What it is |
|---|---|
<profile>/run/engine.sock | The engine protocol. |
<profile>/run/engine.json | The engine’s pid, socket and accounts, plus detached: true for a detached engine. Rewritten when accounts are added or removed. |
The run/ directory is created with mode 0700, and the engine accepts a connection only when the peer’s user id matches its own. See Security model.
Clients find the engine by reading the discovery files in <profile>/run/. A file whose process is gone and whose socket doesn’t answer is treated as left over from a crash and skipped. The airpost command exits with code 3 when it finds no live engine.
The protocol
The protocol is JSON-RPC 2.0, one JSON object per line (NDJSON). The types are defined in the airpost-ipc crate, which also produces a JSON Schema that @airpost/client generates its TypeScript types from. The current protocol version is 1.
hello
The first request on every connection. The client names itself and the protocol version; the engine answers with its version, pid, accounts, whether it’s detached, and a features list such as snooze, unsubscribe, draft-pipeline and expiration-executor. Clients check features instead of version numbers.
Reads and live queries
threads.list, messages.get, folders.list, query and the rest return data. query.subscribe keeps a query live: the engine re-runs it when matching rows change, at most every 50 ms, and sends query.changed with the rows that entered or changed.
Changes
Intents such as threads.archive, threads.snooze or draft.send, or a raw task.queue. The engine replies once it has applied the local phase, and reports progress through deltas and task.done.
subscribe
Opts the connection into delta notifications: every model the engine saves or removes, filtered by account and class if you ask.
A request without an id is a notification, which the engine accepts and doesn’t answer. Batches aren’t supported. Slow calls (AI, integrations, file downloads and some reads) run on worker pools and can answer out of order; when a pool’s queue is full the engine answers “busy” at once instead of queueing forever.
{"jsonrpc":"2.0","id":1,"method":"hello","params":{"protocol":1,"client":"my-script"}}
{"jsonrpc":"2.0","id":1,"result":{"protocol":1,"engine":"…","pid":4242,"accounts":[…],"features":["snooze","unsubscribe",…],"detached":false}}
A subscriber that stops reading and lets its queue fill is sent disconnect and closed, so one stuck client can’t slow the engine down for the others.
Clients attaching
In the desktop app, the main process starts the engine and keeps a pipe to its stdin and stdout. That pipe is the control channel for the calls that carry credentials or manage the engine, such as account.add, engine.resetDatabase and engine.shutdown. Secrets go one way: from the client to the engine. The engine never sends a password back over the socket.
Each app window opens its own socket connection for reads, live queries and tasks. The CLI, airpost-mcp and the gateway connect the same way. Everything a connection does acts as you, because only you can open the socket.
Detached mode
A detached engine (airpost-engine --mode serve --detached) has no parent. It’s what the background service runs, and what a server runs. The differences:
- There’s no stdin control channel. Local, non-relayed socket connections can call the engine methods that the parent would otherwise send (account management,
engine.shutdownand the like), exceptcredentials.import. - Nothing secret is written to stdout, which is a terminal or a service log.
engine.jsonandhellosaydetached: true.
When the desktop app starts and finds a detached engine of the same build, it joins it instead of starting its own. If the running engine is a different build installed as a unit, the app restarts the unit first; any other engine is asked to stop.
Lifecycle
- Started by the app. When no engine is running, the desktop app starts one with pipes. If its stdin stays closed for more than 30 seconds (the app went away), the engine exits with code 141.
- Started as a service. With Keep Airpost running in the background on, or after
airpost engine install, launchd or systemd runs a detached engine at login and restarts it after a failed exit. The unit is written so it doesn’t fight the app’s own engine for the socket. See Background services. - Not socket-activated. The engine syncs with no client connected, so it has to be running already. The gateway and the MCP HTTP server are socket-activated; the engine isn’t.
- One per profile. A second engine on the same profile would find the socket taken. Use
--config-dir(orCONFIG_DIR_PATH) for a separate profile.
Other modes
serve is the only mode clients use. The others exist for setup and debugging: sync (one account, the original Mailspring-Sync interface), test (check an account’s settings), migrate, reset, install-check and import-legacy (bring over a Mailspring profile). The flags are in The engine.
Related
- Sync: what the account threads do.
- Profiles and data: the files the engine writes.
- Architecture: the contributor-level view.