Always-on VPS
Run the engine and the gateway on a small VPS with Docker Compose and Caddy, so mail syncs, rules run and scheduled sends go out 24/7.
What you’ll build
A Linux VPS running the Airpost engine headless, the gateway with the web client, and Caddy for TLS, all from deploy/server/ in the repository. Your accounts sync around the clock, mail rules run on arriving mail, and drafts you schedule with Send Later go out on time even when your laptop is closed. You reach it at https://mail.example.com from any paired browser.
Prerequisites
- A Linux VPS with Docker and the Compose plugin. 1 vCPU and 1 GB of RAM is enough for a few accounts; disk depends on how much mail you have.
- A DNS name (
mail.example.comhere) with an A or AAAA record pointing at the VPS. - Ports 80 and 443 open to the internet, for Caddy’s certificate and the web client.
- A checkout of the repository, since the image isn’t published yet. The CLI itself isn’t needed on the VPS: the image includes it. See Install the CLI for the rest.
Get the compose setup
git clone https://github.com/airpost-mail/airpost.git
cd airpost/deploy/server
cp .env.example .env
Configure
Edit .env:
AIRPOST_DOMAIN=mail.example.com
AIRPOST_VERSION=dev
COMPOSE_PROFILES=web,proxy
web runs the gateway and the web client, proxy runs Caddy. Leave backend off. Add mcp later if you want agents (see Variations).
Build and start
docker compose -f compose.yaml -f compose.build.yaml up -d --build
The first build compiles the Rust binaries and the web client and takes a while. Once a release image exists, docker compose up -d with a version in AIRPOST_VERSION replaces this step.
Check it
docker compose ps
docker compose exec engine airpost status
Every service shows healthy, and airpost status lists one engine with no accounts.
Add your accounts
IMAP asks for the password and finds the servers for most providers. For Gmail and Microsoft, open the printed address on your own computer, sign in, and paste back the http://127.0.0.1:12141/?code=... address the browser ends on. That page doesn’t load, which is expected.
Run docker compose exec engine airpost status again; the account shows its state while it syncs.
Pair your browser
docker compose exec gateway airpost-gateway pair --admin --name laptop
Open the printed https://mail.example.com/pair#<code> link. The code works once and expires after 10 minutes. Pair other devices without --admin; see Mail on your phone.
Expected output
$ docker compose ps
NAME SERVICE STATUS
airpost-server-caddy-1 caddy Up 3 minutes
airpost-server-engine-1 engine Up 3 minutes (healthy)
airpost-server-gateway-1 gateway Up 3 minutes (healthy)
The web client loads at https://mail.example.com with your inbox. A draft scheduled with Send Later, from the web client or with airpost draft send <id> --at 'tomorrow 9:00', goes out at 9:00 with every one of your devices off. docker compose exec engine airpost draft scheduled lists what’s waiting.
How it works
Each component is its own container from one image, read-only with all capabilities dropped, and Docker restarts any that stops. The engine (airpost-engine --mode serve --detached) holds the accounts, syncs them, applies mail rules and performs scheduled sends. Credentials are encrypted in the profile volume with a key kept in the separate engine-key volume. The gateway serves the web client and talks to the engine over the profile’s socket. Caddy gets the certificate for AIRPOST_DOMAIN and routes everything but /mcp and the backend paths to the gateway.
The engine logs into the profile rather than to Docker:
docker compose exec engine airpost logs you@example.com -f
docker compose logs gateway
Variations
- Agents over HTTP. Add
mcptoCOMPOSE_PROFILESand rundocker compose up -d. The policy isdeploy/server/mcp.json(read-only by default). Get the bearer token withdocker compose exec mcp airpost-mcp tokenand point a client athttps://mail.example.com/mcp. See MCP over HTTP. - Your own reverse proxy. Drop
proxyand add-f compose.own-proxy.yaml; the gateway is then on127.0.0.1:5180. See On a server. - No Docker. Install the CLI on the VPS and use
airpost engine install --key-file ~/.config/airpost-engine.key,airpost gateway install --public-url https://mail.example.comandloginctl enable-linger "$USER", with a TLS proxy in front. - Rules on the server.
docker compose exec engine airpost rules add --name Receipts --if 'from contains shop.example' --then 'move Receipts'.
Backups and upgrades
Back up profile and engine-key separately. For a consistent copy, stop the engine first:
docker compose stop engine
docker run --rm -v airpost-server_profile:/p:ro -v "$PWD":/out alpine \
tar czf /out/airpost-profile.tgz -C /p .
docker compose start engine
To upgrade from a checkout, git pull and run the build command again. The engine migrates its database on start without keeping the old one, so back up first.
Cleanup
docker compose down # stop and remove the containers, keep the volumes
docker compose down -v # also delete the profile and key volumes
Remove the DNS record if you no longer need it. Your mail stays on your mail servers.