Airpost
Web client and gateway

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.

Troubleshooting