Airpost
Web client and gateway

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

--config-dirpath

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.

--bindaddr:portdefault:127.0.0.1:5180

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.

--public-urlurl

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.

--insecure-public-urlbooldefault:false

Env AIRPOST_GATEWAY_INSECURE_PUBLIC_URL. Accept a plain http public URL on a non-loopback host. The device cookie then travels unencrypted.

--allow-originorigin

Env AIRPOST_GATEWAY_ALLOW_ORIGINS (comma-separated). Another origin allowed to call the gateway, such as a Vite dev server. Repeatable.

--trusted-proxiesCIDR listdefault:127.0.0.0/8,::1

Env AIRPOST_TRUSTED_PROXIES (comma-separated). Peers whose X-Forwarded-For the gateway believes when it finds the client address for rate limits.

--web-rootpath

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.jsonPaired devices and pending codes, as hashes
gateway.jsonWritten 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 serveEvery account in one process
--detachedNo 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
--verboseMore logging
Env
CONFIG_DIR_PATHThe profile directory. Required. The image sets /profile.
AIRPOST_ENGINE_KEY_FILESelects 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_DIRECTORYSet by systemd’s LoadCredential=; the engine reads the key from the credential airpost-engine-key there.
AIRPOST_ENGINE_SECRET_STOREkeychain or secret-service: use the OS store instead.
AIRPOST_GMAIL_CLIENT_ID, AIRPOST_GMAIL_CLIENT_SECRETYour own Google OAuth client; empty uses the built-in one.
AIRPOST_O365_CLIENT_IDYour 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.

VariableDefault
AIRPOST_DOMAINrequiredThe hostname clients reach. Caddy gets its certificate; MCP accepts only this Host.
AIRPOST_VERSIONrequiredImage tag. dev with compose.build.yaml.
AIRPOST_IMAGEghcr.io/airpost/airpost-serverImage name
COMPOSE_PROFILESweb,proxyComponents besides the engine: web, proxy, mcp (and backend, not available yet)
AIRPOST_PUBLIC_URLhttps://$AIRPOST_DOMAINSet for a non-standard port or a local trial (http://127.0.0.1:5180)
AIRPOST_SUBNET172.31.86.0/24The compose network, also the gateway’s trusted proxies. Change it only if it collides.
AIRPOST_HTTP_PORT, AIRPOST_HTTPS_PORT80, 443Caddy’s published ports
AIRPOST_GATEWAY_PORT, AIRPOST_MCP_PORT5180, 2587Ports on 127.0.0.1 with compose.own-proxy.yaml
AIRPOST_GMAIL_CLIENT_ID, AIRPOST_GMAIL_CLIENT_SECRET, AIRPOST_O365_CLIENT_IDemptyPassed 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

VolumeMounted byHolds
profileengine, gateway, mcpDatabase, settings, logs, the engine socket, gateway and MCP state
engine-keyengine onlyengine.key
caddy-data, caddy-configcaddyCertificates

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.