On your computer
Run the gateway next to the engine on your own machine and use Airpost from a browser.
The gateway can run next to the engine on your own computer. By default it listens on 127.0.0.1:5180, so only browsers on that machine can reach it.
From the desktop app
The desktop ships airpost-gateway and the built web client. In Preferences > General, turn on Web access from this computer. That installs the gateway as a user service (it runs airpost gateway install --web-root <dir>). Pair a browser prints a code and link (it runs airpost gateway pair).
From the CLI
Have an engine running
The gateway needs a serve engine on the same profile: the desktop’s while it’s open, or a detached one that keeps running without it. See Engine.
Install the gateway service
airpost gateway install
This writes a launchd agent (macOS) or systemd user .socket unit (Linux) that listens on --bind (default 127.0.0.1:5180) and starts the gateway on the first connection. Options and the other unit commands are in Services.
Pair this browser
airpost gateway pair
Open the printed link on this machine. See Pairing browsers.
Running it by hand
From a checkout (Building from source):
cargo build --release -p airpost-gateway
(cd apps/web && VITE_AIRPOST_ENGINE=gateway npm run build)
target/release/airpost-gateway serve --web-root apps/web/dist
target/release/airpost-gateway pair
Without --config-dir (or AIRPOST_CONFIG_DIR) the gateway uses the desktop’s profile, as airpost does. With --bind 127.0.0.1:0 the system picks the port; the pairing link and <profile>/gateway/gateway.json name it.
Only one gateway runs per profile. A second one exits with an error.
Reaching it from other devices
The gateway speaks plain HTTP. To use it from another device, keep it on 127.0.0.1 and put TLS in front: a reverse proxy, or a private network with its own certificate (for example tailscale cert). Then set the public URL:
airpost gateway install --public-url https://airpost.example.com
The proxy setup is the same as on a server: Reverse proxy.
The gateway refuses a plain http public URL on a non-loopback host unless you pass --insecure-public-url. With it, the device cookie travels unencrypted.
Web client development
Run the gateway with --allow-origin http://localhost:5173, and npm run dev in apps/web with VITE_AIRPOST_ENGINE=gateway. Vite proxies /gateway to it.
Logs and status
airpost status # the engine and its accounts
airpost logs gateway -f # the installed gateway service
airpost logs engine -f # a detached engine service
airpost logs reads a service’s log without needing the engine. When you run the gateway by hand it logs to stderr; RUST_LOG=debug shows more. <profile>/gateway/gateway.json names the running gateway’s pid, public URL and version.