Airpost
How Airpost works

Security model

Airpost's trust boundaries: who can reach the engine socket, what agents can do, how browsers are paired, where credentials are kept, and the privacy defaults.

The engine holds everything sensitive: your mail, your account credentials and the ability to send as you. Airpost’s security model is mostly about who can reach the engine and what they can do once they have.

The short version: any program running as your user on your computer has full access, because that’s the trust check. Agents get the access level you choose. Remote devices get in only through the gateway, after you pair them, and with a reduced set of methods unless you grant more.

Trust boundaries

BoundaryWho is on the other sideWhat protects it
Engine socketProcesses on this computerFile permissions and a peer user id check
MCPAI agentsThe access level and visible accounts in mcp.json, a bearer token for HTTP
GatewayBrowsers and remote devicesOne-time pairing codes, device cookies, scopes
Secret storeAnyone reading the diskOS keychain, or AES-256-GCM with a separate key
Your providerThe networkTLS, OAuth where the provider supports it

The engine socket

The engine is never on the network. It listens on a Unix domain socket, <profile>/run/engine.sock, and three things keep it private:

  • File modes. The engine runs with a umask of 077, so every file and directory it creates (the database, logs, attachments, the socket) is readable by your user only. The run/ directory is 0700 and the socket 0600.
  • Peer check. On every connection the engine asks the OS for the peer’s user id (SO_PEERCRED on Linux) and refuses anyone who isn’t the user it runs as.
  • No secrets back. Credentials go into the engine and never come out over the socket. A client can set or delete a secret by name, and ask whether one exists, but not read it.

Inside that boundary there are no further checks: every local connection acts as you, with the same power as the app. This is deliberate. Another program running as you could already read your files, so a password on the socket wouldn’t add much. It does mean that malware running as your user can use the engine, and that the airpost CLI isn’t limited by the MCP access level.

MCP access levels

airpost-mcp is the boundary between AI agents and your mail. It connects to the engine with full access and then decides, per call, what the agent may do. The policy is in <profile>/mcp.json, edited in Preferences > MCP.

LevelaccessLevelAdds
Read mailread-only (default)Listing, searching and reading mail, attachments, events and contacts
Read and draftread-writeDrafts, archive, trash, move, labels, snooze, reminders, undo, events without guests
Read, draft and sendread-write-sendSending, scheduling, unsubscribe, RSVPs and events with guests

Unsubscribe and events with guests are in the send level because they can send mail on your behalf.

  • Fails closed. An unknown level is treated as read-only. A mcp.json that doesn’t parse makes every tool fail, so a typo can’t widen access. The file is read again on every call.
  • Hidden accounts and folders aren’t listed, and their ids answer “not found”, the same as if they didn’t exist.
  • Transports. stdio is for apps on this computer that start airpost-mcp themselves, such as Claude Desktop or Claude Code. HTTP (airpost-mcp http, off by default, on 127.0.0.1) needs Authorization: Bearer <token> with the token in <profile>/mcp-token, created owner-only on first use.
  • Audit log. Every tool call and resource read is appended to <profile>/mcp-audit.log: time, client, account, tool, outcome (ok, error or denied) and a summary of the arguments with message bodies replaced by their length and credential-like keys dropped.

See Access levels and Audit log.

Gateway pairing and tokens

The gateway is the only part that puts the engine on a network. It serves the web client and relays requests to the engine socket for devices you’ve paired.

  • Codes are 12 characters, work once, and expire after 10 minutes by default (at most an hour). Attempts are rate limited per client address and overall.
  • Cookies are HttpOnly and SameSite=Strict, and Secure with the __Host- prefix over HTTPS. The gateway stores only hashes of codes and tokens, in <profile>/gateway/devices.json. Unused devices are dropped after 180 days, admin devices after 30.
  • Scopes. A device paired without --admin can read mail, triage it and work on drafts. Account, secret and engine methods, and tasks that write to a local path, need the admin scope. AI provider settings (core.ai.*) can’t be changed from any remote device, admin or not, because that would let a remote device point the engine at any URL.
  • Checked twice. The gateway checks each request against the policy in airpost-ipc, and the engine checks it again for every connection whose hello says relayed.
  • Origin and Host checks on every request, and plain HTTP refused off loopback unless you opt in.

See Pairing browsers and Self-hosting security.

Credential storage

WhereBackendNotes
macOSKeychain, service Airpost EngineOne item for the whole keyset, so you’re asked at most once.
Linux desktopSecret ServiceSame keyset in one item.
Server, or no keyringsecrets.enc, AES-256-GCMKey from AIRPOST_ENGINE_KEY_FILE or systemd’s $CREDENTIALS_DIRECTORY.

There’s no plaintext fallback. accounts.json holds account settings without passwords or tokens. Gmail and Microsoft sign in with OAuth, so Airpost holds a refresh token and never sees your password; IMAP accounts store the password you enter. Authentication payloads are never written to the logs, even with --verbose.

The file store keeps credentials out of a leaked profile or backup, as long as the key isn’t stored with it. In the server image the key is on a volume only the engine’s container mounts, so the gateway and MCP containers can read the profile (they need the socket) but can’t decrypt credentials.

What this doesn’t protect against

  • Root, or malware running as you. Either can use the socket, read the database, or read the key file.
  • A compromised gateway or MCP process. It can act through the socket as the profile’s owner, beyond its own policy.
  • A paired device that’s stolen. Its cookie works until you revoke it or it expires. Revoke it with airpost-gateway devices revoke <id>.
  • A key file stored next to secrets.enc. Then anyone with the backup has both.
  • Your provider. The provider already has your mail; Airpost doesn’t add encryption at rest on the server side.

Privacy defaults

Nothing goes to an Airpost service unless you connect an Airpost server. The defaults:

ProtectionDefault
Remote images blocked until you load themOn
Tracking pixels from known trackers removedAlways on
Contact photos from GravatarOff
AI featuresOff
Integrations (translation, grammar, contact details)Off
MCP access for agentsOff until you allow it, then read-only
Web access (gateway)Off; when on, bound to 127.0.0.1:5180
MCP over HTTPOff; when on, bound to 127.0.0.1
Drafts saved to the serverOn, per account

What is sent where when you turn something on is listed in Privacy.