Airpost
Web client and gateway

Security

What the gateway exposes, what protects it, what it doesn't protect against, and how to run it safely.

The engine holds your mail and your account credentials and listens only on a Unix socket, reachable by its own user. The gateway is the one piece that puts it on the network, so most of this page is about the gateway.

What’s exposed

ComponentListens onReachable by
Engine<profile>/run/engine.sockProcesses of the same user only (peer uid check)
Gateway127.0.0.1:5180 by default; 0.0.0.0:5180 inside the server imageAnyone who can reach the port can load the web client and the pairing page. Mail and the engine need a paired device’s cookie.
MCP (optional)/mcp on the serverClients with its bearer token. See Agents.

Anyone who reaches the gateway’s port without a cookie can fetch the static web client, call GET /healthz, and try pairing codes. Everything else answers only to a paired device.

What protects the gateway

  • One-time codes. A code is 12 characters from a 32-character alphabet, works once, and expires after 10 minutes by default (at most an hour). Pairing is rate limited to 5 attempts per minute per client address (IPv4, or IPv6 /64), and to 30 per hour overall while a code is pending. The global limit never counts loopback clients.
  • Device cookies. HttpOnly, SameSite=Strict, and over HTTPS a Secure __Host- cookie. The gateway stores only hashes of tokens and codes. Unused devices are dropped after 180 days, admin devices after 30.
  • Scopes. Only --admin devices can use account, secret and engine methods. Other devices get mail reads, triage and drafts.
  • Host and Origin checks. Every request must carry the public URL’s Host; every state-changing request and every WebSocket must come from its origin (or one you add with --allow-origin).
  • Plain HTTP refused off loopback. A non-loopback http public URL needs --insecure-public-url, and the gateway logs a warning when it runs that way.
  • Limits. At most 8 WebSockets per device and 64 in total, 10 WebSocket upgrades per device per minute, uploads up to 25 MiB.
  • Attachments. Downloads are served as attachments in a CSP sandbox. Inline display is allowed only for PNG, JPEG, GIF and WebP, recognized from the bytes.

Credentials on a server

The engine keeps account settings in accounts.json and passwords, refresh tokens and integration and AI keys in secrets.enc, both in the profile volume. secrets.enc is encrypted with AES-256-GCM using the key in /keys/engine.key, on the engine-key volume, which only the engine’s container mounts.

The gateway and MCP containers mount profile because the engine’s socket is there. They can read the mail database (which they serve anyway) but not the credentials.

What it doesn’t protect against

  • Root on the host, or anyone holding both volumes, or a backup of both.
  • A compromised gateway or MCP container. It can act through the socket, which treats every connection from the profile’s user as the owner.
  • A stolen device that is still paired. Its cookie works until you revoke it or it expires.
  • A passphrase-locked keychain. The server doesn’t offer one yet, so the key sits on disk unless you mount it from elsewhere.

Rate limits and proxies

The gateway rate-limits pairing by client address. Behind a proxy, every client shares the proxy’s address unless the gateway trusts the proxy’s X-Forwarded-For. Set --trusted-proxies (AIRPOST_TRUSTED_PROXIES) to your proxy’s addresses only; anyone else connecting from a trusted address could choose their own rate-limit key. The compose file trusts its own network.

Recommendations

  • Keep the gateway on 127.0.0.1 and put TLS in front: Caddy from the compose setup, your own proxy, or a private network such as Tailscale. Don’t use --insecure-public-url across a network you don’t control.
  • Pair devices with --admin only when you need to manage accounts from them, and revoke them after.
  • Review airpost-gateway devices list now and then and revoke what you don’t recognize.
  • Back up engine-key somewhere other than the profile backups, or mount the key from a secrets manager. See Configuration.
  • Leave the mcp profile off unless you use it, and keep its policy at read-only until you need more.
  • Keep AIRPOST_VERSION current. Back up profile before an upgrade.