Configuration
Every flag and environment variable of airpost-gateway and the server engine, and the variables of the Compose setup.
The gateway and the engine have no config file. They take flags and environment variables; a flag wins over its variable.
airpost-gateway
airpost-gateway [--config-dir <dir>] [serve] [options]
airpost-gateway pair [--admin] [--name <device>] [--ttl 10m] [--json]
airpost-gateway devices list [--json] | rename <id> <name> | revoke <id>
airpost-gateway healthcheck [--bind <addr>]
serve is the default command. Serve options go after serve (or with no command); airpost-gateway --bind X pair is refused.
serve
Env AIRPOST_CONFIG_DIR. The engine’s profile directory; the gateway keeps its state in <dir>/gateway/. Default: the desktop’s profile. Applies to every command.
Env AIRPOST_GATEWAY_BIND. Port 0 lets the system pick one. When the gateway is started by its launchd or systemd socket unit, it uses that socket instead. The server image sets 0.0.0.0:5180.
Env AIRPOST_GATEWAY_PUBLIC_URL. Where browsers reach the gateway, for example https://airpost.example.com. Defaults to the bind address when it is loopback; required otherwise. The gateway checks the Host and Origin headers against it.
Env AIRPOST_GATEWAY_INSECURE_PUBLIC_URL. Accept a plain http public URL on a non-loopback host. The device cookie then travels unencrypted.
Env AIRPOST_GATEWAY_ALLOW_ORIGINS (comma-separated). Another origin allowed to call the gateway, such as a Vite dev server. Repeatable.
Env AIRPOST_TRUSTED_PROXIES (comma-separated). Peers whose X-Forwarded-For the gateway believes when it finds the client address for rate limits.
Env AIRPOST_GATEWAY_WEB_ROOT. The built web client (apps/web/dist, built with VITE_AIRPOST_ENGINE=gateway). The server image sets /usr/share/airpost/web.
RUST_LOG sets the log level (default info). Logs go to stderr.
Files in <profile>/gateway/
| File | |
|---|---|
devices.json | Paired devices and pending codes, as hashes |
gateway.json | Written while serve runs: pid, public URL, version, build |
incoming/ | Uploads in progress, deleted once handed to the engine |
airpost gateway install
The CLI installs the gateway as a service with --bind, --web-root, --public-url and --bin. See Services.
Engine (server)
On a server the engine runs as airpost-engine --mode serve --detached. See Engine for its modes.
| Flag | |
|---|---|
--mode serve | Every account in one process |
--detached | No parent process: local connections on the socket take the parent’s methods (adding and removing accounts) |
--socket <path> | Listen there instead of <profile>/run/engine.sock |
--verbose | More logging |
| Env | |
|---|---|
CONFIG_DIR_PATH | The profile directory. Required. The image sets /profile. |
AIRPOST_ENGINE_KEY_FILE | Selects the file secret store: account secrets go to <profile>/secrets.enc, encrypted with the key in this file. The engine creates the key if the file is missing. The image sets /keys/engine.key. |
CREDENTIALS_DIRECTORY | Set by systemd’s LoadCredential=; the engine reads the key from the credential airpost-engine-key there. |
AIRPOST_ENGINE_SECRET_STORE | keychain or secret-service: use the OS store instead. |
AIRPOST_GMAIL_CLIENT_ID, AIRPOST_GMAIL_CLIENT_SECRET | Your own Google OAuth client; empty uses the built-in one. |
AIRPOST_O365_CLIENT_ID | Your own Microsoft OAuth client; empty uses the built-in one. |
Without a keychain, a Secret Service or a key file, the engine has nowhere to store secrets and can’t add accounts. There is no plaintext store.
Compose variables
Set in deploy/server/.env.
| Variable | Default | |
|---|---|---|
AIRPOST_DOMAIN | required | The hostname clients reach. Caddy gets its certificate; MCP accepts only this Host. |
AIRPOST_VERSION | required | Image tag. dev with compose.build.yaml. |
AIRPOST_IMAGE | ghcr.io/airpost/airpost-server | Image name |
COMPOSE_PROFILES | web,proxy | Components besides the engine: web, proxy, mcp (and backend, not available yet) |
AIRPOST_PUBLIC_URL | https://$AIRPOST_DOMAIN | Set for a non-standard port or a local trial (http://127.0.0.1:5180) |
AIRPOST_SUBNET | 172.31.86.0/24 | The compose network, also the gateway’s trusted proxies. Change it only if it collides. |
AIRPOST_HTTP_PORT, AIRPOST_HTTPS_PORT | 80, 443 | Caddy’s published ports |
AIRPOST_GATEWAY_PORT, AIRPOST_MCP_PORT | 5180, 2587 | Ports on 127.0.0.1 with compose.own-proxy.yaml |
AIRPOST_GMAIL_CLIENT_ID, AIRPOST_GMAIL_CLIENT_SECRET, AIRPOST_O365_CLIENT_ID | empty | Passed to the engine |
A typical .env for a server behind Caddy, with MCP on:
AIRPOST_DOMAIN=airpost.example.com
AIRPOST_VERSION=0.1.0
COMPOSE_PROFILES=web,proxy,mcp
AIRPOST_SUBNET=172.31.86.0/24
And for a host that already runs nginx, on non-default local ports:
AIRPOST_DOMAIN=airpost.example.com
AIRPOST_VERSION=0.1.0
COMPOSE_PROFILES=web
AIRPOST_GATEWAY_PORT=15180
started with docker compose -f compose.yaml -f compose.own-proxy.yaml up -d. .env.example also lists AIRPOST_SIGNUP, AIRPOST_BACKUP_INTERVAL, AIRPOST_BACKUP_KEEP and AIRPOST_LOG_FORMAT; they only affect the backend.
deploy/server/mcp.json is the MCP policy, mounted read-only into the mcp container. See Access levels.
Volumes
| Volume | Mounted by | Holds |
|---|---|---|
profile | engine, gateway, mcp | Database, settings, logs, the engine socket, gateway and MCP state |
engine-key | engine only | engine.key |
caddy-data, caddy-config | caddy | Certificates |
To keep the key off the server’s disks, mount your own file instead of the engine-key volume: at least 32 random bytes (openssl rand -hex 32), owned by uid 65532, mode 0600, for example from a secrets manager’s tmpfs.