Airpost
Web client and gateway

On a server

Run the engine and the gateway on a Linux server with Docker Compose, behind Caddy or your own reverse proxy.

On a server the engine runs headless: your mail syncs and scheduled sends go out while every device is off. You use it through the web client, served by the gateway, and optionally through MCP for agents.

deploy/server/ in the repository is a Docker Compose setup. It runs one service per component, all from the airpost-server image:

ServiceProfileDefaultWhat it runs
enginealways ononairpost-engine --mode serve --detached: syncs the accounts, keeps their credentials
gatewaywebonairpost-gateway serve with the web client
caddyproxyonTLS for AIRPOST_DOMAIN; leave it out behind your own proxy
mcpmcpoffairpost-mcp http at https://<domain>/mcp, for agents with a bearer token
backendbackendoffNot available yet; leave it off

Each runs as a separate process in its own container, read-only, with all capabilities dropped. Docker restarts one that stops. The image has no shell; it includes the airpost CLI for admin inside the engine’s container.

The image ghcr.io/airpost/airpost-server isn’t published yet. Until it is, build it from a checkout (step 3).

The files in deploy/server/

FileWhat it does
compose.yamlThe services, volumes and network. Start here.
.env.exampleEvery variable you set, with comments. Copy it to .env, which .gitignore keeps out of git.
CaddyfileCaddy’s routes for AIRPOST_DOMAIN, used with the proxy profile.
compose.own-proxy.yamlOverride: publishes gateway, MCP and backend on 127.0.0.1 for a host proxy or a local trial.
compose.build.yamlOverride: builds airpost-server:dev from the checkout instead of pulling.
DockerfileThe image: web client, all five binaries, distroless runtime.
Dockerfile.dockerignoreKeeps the build context to the sources the Dockerfile copies.
mcp.jsonThe MCP policy, mounted read-only into the mcp container.

compose.yaml

The project is named airpost-server, so volumes are airpost-server_profile and so on. Every Airpost service inherits one anchor, x-airpost:

x-airpost: &airpost
  image: ${AIRPOST_IMAGE:-ghcr.io/airpost/airpost-server}:${AIRPOST_VERSION:?set AIRPOST_VERSION in .env}
  restart: unless-stopped
  init: true
  read_only: true
  tmpfs:
    - /tmp
  cap_drop: [ALL]
  security_opt: ["no-new-privileges:true"]
  networks: [airpost]

AIRPOST_VERSION has no default: Compose refuses to start without it. The root filesystem is read-only, with /tmp as tmpfs; the only writable paths are the mounted volumes.

  • engine runs airpost-engine --mode serve --detached, mounts profile at /profile and engine-key at /keys, and passes the three OAuth client variables. Its health check is airpost status every 30 seconds with a 60-second start period. stop_grace_period: 30s gives it time to finish writes on docker compose stop.
  • gateway (profile web) runs airpost-gateway serve and waits for the engine to be healthy. It sets AIRPOST_GATEWAY_PUBLIC_URL from AIRPOST_PUBLIC_URL, falling back to https://$AIRPOST_DOMAIN, and AIRPOST_TRUSTED_PROXIES to the compose subnet. The bind address (0.0.0.0:5180) and web root come from the image.
  • mcp (profile mcp) runs airpost-mcp http --bind 0.0.0.0, reads its policy from /etc/airpost/mcp.json (AIRPOST_MCP_POLICY), and accepts only AIRPOST_DOMAIN as Host (AIRPOST_MCP_ALLOWED_HOSTS).
  • backend (profile backend) runs airpost-backend serve with its own backend-data and backend-backups volumes. It isn’t available yet; leave it off.
  • caddy (profile proxy) is the stock caddy:2 image. It publishes AIRPOST_HTTP_PORT (80) and AIRPOST_HTTPS_PORT (443, TCP and UDP for HTTP/3), mounts the Caddyfile read-only, and keeps certificates in caddy-data and caddy-config. Its depends_on entries are required: false, so it starts whichever components are on.

The airpost network has a fixed subnet (AIRPOST_SUBNET, default 172.31.86.0/24) so the gateway can trust it as a proxy range.

The image

The Dockerfile has three stages:

  1. web (node:22-bookworm-slim) runs npm ci and VITE_AIRPOST_ENGINE=gateway npm run build in apps/web.
  2. build (rust:1.92-slim-bookworm) runs cargo build --release --locked for airpost-engine, airpost-gateway, airpost-backend, airpost-mcp and airpost, and writes third-party notices.
  3. The runtime is gcr.io/distroless/cc-debian12:nonroot: no shell, no curl. Binaries go to /usr/local/bin, the web client to /usr/share/airpost/web, licences to /usr/share/doc/airpost.

The image sets these defaults, which the compose file relies on:

EnvValue
CONFIG_DIR_PATH, AIRPOST_CONFIG_DIR/profile
AIRPOST_ENGINE_KEY_FILE/keys/engine.key
AIRPOST_GATEWAY_WEB_ROOT/usr/share/airpost/web
AIRPOST_GATEWAY_BIND0.0.0.0:5180
AIRPOST_DATA_DIR, AIRPOST_BIND/data, 0.0.0.0:5101 (backend)

/profile, /keys, /data and /backups are created empty and owned by uid 65532, so fresh volumes are writable. To build it by hand from the repository root:

docker build -f deploy/server/Dockerfile -t airpost-server .

An image built without the SOURCE_URL and SOURCE_TAG build args says in /usr/share/doc/airpost/SOURCE.txt that it must not be published.

mcp.json

{
  "accessLevel": "read-only",
  "enabledAccounts": {},
  "http": {"enabled": true, "port": 2587}
}

Edit it on the host and run docker compose restart mcp. See Access levels.

Setup

You need a Linux machine with Docker, a DNS name pointing at it, and ports 80 and 443 open.

Get the compose files

Copy deploy/server/ from the repository and change into it.

Configure

cp .env.example .env

Set AIRPOST_DOMAIN, AIRPOST_VERSION and COMPOSE_PROFILES (default web,proxy; add mcp to run it). All variables are in Configuration.

Start it

Published image
docker compose up -d

Check it

docker compose ps shows each service healthy. docker compose exec engine airpost status lists the engine and its accounts (none yet).

Add an account and pair a browser

Trying it without a domain

On one machine, without TLS:

AIRPOST_DOMAIN=127.0.0.1 \
AIRPOST_PUBLIC_URL=http://127.0.0.1:5180 \
COMPOSE_PROFILES=web \
docker compose -f compose.yaml -f compose.own-proxy.yaml up -d

The web client is then at http://127.0.0.1:5180.

Turning components on and off

Add a profile to COMPOSE_PROFILES and run docker compose up -d. To turn one off, take it out and remove its container, for example docker compose rm -sf mcp.

Adding mail accounts

Use the airpost CLI in the engine’s container. For IMAP, Airpost finds the servers for most providers; --imap-host, --smtp-host and the other flags of airpost account add --help override them:

docker compose exec engine airpost account add you@example.com

It asks for the password (or reads it with --password-stdin), tests the account and stores it.

Gmail and Microsoft accounts sign in in a browser, which on a server runs on another computer:

docker compose exec engine airpost account add you@gmail.com --provider gmail --paste

Open the address it prints, sign in, and paste back the http://127.0.0.1:12141/?code=… address the browser ends on (that page doesn’t load; that’s expected). --provider office365 and outlook work the same way.

A browser paired with --admin can also add IMAP accounts in the web client’s Settings > Accounts.

docker compose exec engine airpost status shows each account’s state. docker compose exec engine airpost logs <email> -f follows its log.

TLS

With the proxy profile, Caddy gets a certificate for AIRPOST_DOMAIN and routes one hostname to every component (deploy/server/Caddyfile):

PathGoes to
/mcpmcp:2587, unbuffered
/ping, /airpost/*, /metadata/*, /deltas/*, /t/*the backend (answers 502 while it’s off)
everything elsegateway:5180: the web client and /gateway/*

Your own reverse proxy

Leave proxy out of COMPOSE_PROFILES and add the compose.own-proxy.yaml override:

docker compose -f compose.yaml -f compose.own-proxy.yaml up -d

The gateway is then on 127.0.0.1:5180 and MCP on 127.0.0.1:2587. Route /mcp to MCP without buffering, and everything else to the gateway. The gateway needs WebSocket upgrades and the original Host header, which it checks.

airpost.example.com {
    handle /mcp {
        reverse_proxy 127.0.0.1:2587 {
            flush_interval -1
        }
    }
    handle {
        reverse_proxy 127.0.0.1:5180
    }
}

Caddy forwards WebSocket upgrades, Host and X-Forwarded-For by default.

The gateway pings every WebSocket every 30 seconds and closes one that has sent nothing for 45 seconds, so a proxy read timeout of 60 seconds (nginx’s default) is enough; 1h above is a margin. Uploads go up to 25 MiB, so the proxy must accept bodies that large.

The gateway reads X-Forwarded-For for its pairing rate limits only from addresses in AIRPOST_TRUSTED_PROXIES. The compose file sets that to the compose network, which covers Caddy and a host proxy reaching the published port. See Security.

Without Docker

deploy/systemd/ has no units for the engine or the gateway. To run them as services on a Linux machine without Docker, install the CLI and use its unit commands: airpost engine install for a detached engine (Engine) and airpost gateway install --public-url https://<domain> for the gateway (Services). These install systemd user units, so on a server run loginctl enable-linger "$USER" once to keep them running after you log out. Put a TLS proxy in front as above.

Backups

VolumeHolds
profileThe mail database, settings, signatures, rules, accounts and their encrypted credentials (secrets.enc), paired browsers (gateway/devices.json), the MCP token and audit log
engine-keyengine.key, which decrypts secrets.enc. Back it up separately from profile.
caddy-dataCertificates. Caddy gets new ones if you lose it.

Mail itself stays on your mail servers. Without profile you add the accounts again and Airpost syncs from scratch. A profile backup without the matching key restores mail and settings, but every account needs its password or sign-in again.

For a consistent copy of the profile, stop the engine first. The gateway and MCP lose the engine while it’s stopped and reconnect when it’s back:

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 run --rm -v airpost-server_engine-key:/k:ro -v "$PWD":/out alpine \
    tar czf /out/airpost-engine-key.tgz -C /k .
docker compose start engine

Store airpost-engine-key.tgz somewhere other than the profile archive.

Restoring

On a fresh host, create the volumes with docker compose create, then unpack both archives into them as uid 65532 and start:

docker compose create
docker run --rm -v airpost-server_profile:/p -v "$PWD":/in alpine \
    sh -c 'tar xzf /in/airpost-profile.tgz -C /p && chown -R 65532:65532 /p'
docker run --rm -v airpost-server_engine-key:/k -v "$PWD":/in alpine \
    sh -c 'tar xzf /in/airpost-engine-key.tgz -C /k && chown -R 65532:65532 /k'
docker compose up -d

Paired browsers keep working if the public URL is unchanged.

Upgrades

Set the new AIRPOST_VERSION in .env, then:

docker compose pull
docker compose up -d
docker compose ps

Compose recreates each container on the new image; the engine starts first and the gateway and MCP wait until it is healthy. From a checkout, git pull and rerun the compose.build.yaml command with --build.

The engine migrates its database when it starts and doesn’t keep a copy of the old one. Back up profile first if you might roll back. Rolling back means restoring that backup, then setting the old AIRPOST_VERSION.

Read the release notes before upgrading across several versions. Browsers reload the web client on their next visit.

Health and logs

Each health check is a command in the image, since there is no shell or curl:

ServiceCheckFails when
engineairpost statusNo engine answers on the profile’s socket (exit code 3)
gatewayairpost-gateway healthcheckThe gateway doesn’t answer GET /healthz. It reports the gateway, not the engine.
mcpairpost-mcp healthcheckMCP doesn’t answer

docker compose ps shows the state of each. To alert on it, watch docker inspect --format '{{.State.Health.Status}}' airpost-server-engine-1 (or your monitoring system’s Docker integration). From outside, a request to https://<domain>/healthz checks Caddy and the gateway together.

Where logs go:

WhatCommand
An account’s sync, send and authdocker compose exec engine airpost logs <email>; add -f to follow, -n 200 for more lines
Gateway: pairing, refused hosts, sessionsdocker compose logs -f gateway
MCP serverdocker compose logs -f mcp
MCP tool callsmcp-audit.log in the profile, one JSON object per line
TLS and routingdocker compose logs -f caddy

The engine writes its logs into the profile, not to Docker. The gateway and MCP log to stderr; set RUST_LOG=debug in their environment for more.

More than one person

A profile belongs to one person. To host a second person on the same machine, run a second Compose project from a copy of deploy/server/ with its own .env:

cp -r deploy/server airpost-bob && cd airpost-bob
cp .env.example .env    # AIRPOST_DOMAIN=bob.example.com, AIRPOST_SUBNET=172.31.87.0/24
docker compose -p airpost-bob -f compose.yaml -f compose.own-proxy.yaml up -d

-p gives it its own volumes (airpost-bob_profile, …). Each project needs its own subnet and, with compose.own-proxy.yaml, its own AIRPOST_GATEWAY_PORT and AIRPOST_MCP_PORT. Only one Caddy can own ports 80 and 443, so with more than one project, put one proxy on the host and route each domain to its project’s ports.

Troubleshooting