Overview
What the gateway and the web client are, and the ways you can run them.
Airpost’s engine syncs your mail and holds your account credentials. It listens only on a Unix socket, reachable by your own user. To read mail from a browser, you run two more pieces next to it:
airpost-gatewayserves the built web client and relays its JSON-RPC WebSocket to the engine’s socket, as the engine’s user. Only browsers you pair with a one-time code get in.- The web client (
apps/web) is Airpost in a browser. The gateway serves it as static files; it talks only to the gateway.
The gateway connects to the serve engine of its profile, found through <profile>/run/engine.json. That can be the engine a running desktop started, a detached engine you installed with airpost engine install, or the engine container of the Airpost server. When that engine stops, browsers show “The engine isn’t running”.
Topologies
| Setup | Where the engine runs | Who reaches the gateway | Page |
|---|---|---|---|
| Local | Your computer (the desktop’s engine, or a detached one) | Browsers on the same machine, on 127.0.0.1:5180 | On your computer |
| Local, remote access | Your computer | Other devices, through a TLS proxy or a private network | On your computer |
| Server | A Linux server, in Docker | Anyone with the URL can load the page; only paired browsers get mail | On a server |
Local
The engine is the desktop’s own, or a detached one from airpost engine install. The gateway reaches it through <profile>/run/engine.sock, as the same user.
Local, remote access
The gateway stays on loopback. TLS ends at the proxy, and --public-url names the address the other devices use.
Server
Every container runs the same image as the same user (uid 65532). The gateway and MCP share the profile volume with the engine because the socket lives there; only the engine mounts engine-key.
On a server the engine runs headless, so mail keeps syncing and scheduled sends go out while all your devices are off. The same server can also run airpost-mcp for agents (see Agents).
The Airpost backend (airpost-backend, for metadata sync and later read receipts) is not available yet. Nothing on these pages needs it.
Users and devices
One engine profile holds one person’s mail. Everything that reaches the gateway with a paired cookie acts as that profile’s owner, with the scope it was paired with. You can pair as many browsers as you like (phone, work laptop, home desktop); each shows up separately in airpost-gateway devices list and you revoke them one at a time. See Pairing browsers.
There are no per-user accounts inside one gateway. To host Airpost for two people, run two profiles: two Compose projects on a server, or two OS users on one computer. On a server shows the Compose version.
The desktop app and a server don’t share a profile. If you use both, they each sync the same mail accounts independently.
Getting the binaries
There is no release yet. Install the CLI as described in Install, or build the engine, gateway and web client yourself: Building from source. The server image (ghcr.io/airpost/airpost-server) isn’t published either; On a server shows how to build it from a checkout.