Background services
Run the engine, the gateway and the MCP HTTP server as launchd or systemd user units with airpost.
airpost installs Airpost’s own programs as user units: a LaunchAgent on macOS, a systemd --user unit on Linux. They keep running after the desktop app quits and work the same on a machine with no desktop. The desktop’s Preferences > General runs these same commands.
| Command | Runs | Starts |
|---|---|---|
airpost engine | airpost-engine --mode serve --detached | At login, and again after a failed exit. |
airpost gateway | airpost-gateway serve | On the first connection to its port. |
airpost mcp-http | airpost-mcp http | On the first connection to its port. |
airpost service | A service plugin’s program | After the engine. |
Subcommands
engine, gateway and mcp-http share these subcommands:
| Subcommand | Description |
|---|---|
install | Write the unit and load it. |
uninstall | Stop the unit and remove it. |
start | Start the installed unit’s program if it isn’t running. |
stop | Stop it until the next login or start. |
restart | Restart it, so it runs the binary now at its path. Run this after an upgrade. |
gateway also has pair, below.
Flags for every subcommand
| Flag | Description |
|---|---|
--unit-dir <DIR> | Write the units here instead of ~/Library/LaunchAgents or ~/.config/systemd/user, and load nothing. Env: AIRPOST_UNIT_DIR. |
--no-load | Write the units but don’t load or start them. |
Flags for install
| Flag | engine | gateway | mcp-http | Description |
|---|---|---|---|---|
--bin <PATH> | yes | yes | yes | The binary. Default: the one beside airpost, or AIRPOST_ENGINE_BIN, AIRPOST_GATEWAY_BIN, AIRPOST_MCP_BIN. |
--key-file <PATH> | yes | Keep the engine’s secrets in a file sealed with this key instead of the OS keychain. Sets AIRPOST_ENGINE_KEY_FILE in the unit. | ||
--bind <ADDR:PORT> | yes | Where the gateway listens. Default 127.0.0.1:5180. | ||
--web-root <DIR> | yes | The built web client. Default: one beside the gateway binary (airpost-web, web or ../share/airpost/web). | ||
--public-url <URL> | yes | Where browsers reach the gateway when it isn’t the bind address, e.g. behind a TLS proxy. | ||
--port <PORT> | yes | The port. Default: http.port in mcp.json. | ||
--replace | yes | yes | yes | Take over a unit that runs another copy of Airpost’s binaries (the desktop’s, or a package manager’s). |
--no-start | yes | yes | yes | Enable the unit for login but don’t start it now. |
--dry-run | yes | yes | yes | Print the units and write nothing. |
Ports must be fixed; port 0 is refused.
The engine
airpost engine install
airpost status
If the desktop’s own engine is running, install only enables the unit, as with --no-start: the unit’s engine would find the socket taken. It starts the next time you log in or when you run airpost engine start after quitting the app. See The engine for what it does.
On a server without a desktop keyring:
airpost engine install --key-file ~/.config/airpost-engine.key
loginctl enable-linger "$USER"
The gateway
airpost gateway install --bind 127.0.0.1:5180
airpost gateway pair
pair prints a one-time code that pairs a browser with the gateway (it runs airpost-gateway pair).
| Flag | Description |
|---|---|
--admin | Grant the admin scope. |
--name <NAME> | The device’s name; otherwise the browser’s. |
--ttl <TTL> | How long the code stays valid: 90s, 10m, 1h (at most 1h). |
Remote access, TLS and pairing are covered in Self-hosting.
MCP over HTTP
airpost mcp-http install
The unit listens on 127.0.0.1 and starts airpost-mcp http on the first connection. It needs http.enabled set in mcp.json in the profile (Preferences > MCP); install refuses otherwise. If AIRPOST_MCP_POLICY is set when you install, the unit keeps it. See MCP over HTTP.
Service plugins
airpost service runs a plugin’s background program (airpost.service in its package.json) after the engine, also while the desktop is closed.
| Subcommand | Description |
|---|---|
service install <PACKAGE> | Copy the plugin’s service binary into <profile>/services/<package>/ and install a unit that runs it. Installs the engine unit first if it’s missing. |
service uninstall <PACKAGE> | Stop the service and remove its unit and binary copy. |
service list | The installed services: source, binary, hash and unit. |
service install flags, besides --unit-dir and --no-load:
| Flag | Description |
|---|---|
--package-dir <DIR> | The plugin’s directory, instead of looking it up in the profile. |
--engine-bin <PATH> | The engine binary for the engine unit. |
--engine-key-file <PATH> | For the engine unit: keep its secrets in a file sealed with this key. |
--expect-sha256 <HEX> | Refuse unless the service binary has this SHA-256 (the one a dry run showed). |
--expect-plan <HEX> | Refuse unless the install would write exactly what a dry run showed (its planSha256). |
--dry-run | Print the binary, its hash and the units, and write nothing. |
Writing a service plugin is covered in Service plugins.
Unit names and files
Units are named after the profile. For the default profile:
| Unit | macOS label (~/Library/LaunchAgents/<label>.plist) | systemd unit (~/.config/systemd/user/) |
|---|---|---|
| Engine | com.airpost.airpost.engine | airpost-engine.service |
| Gateway | com.airpost.airpost.gateway | airpost-gateway.service and .socket |
| MCP HTTP | com.airpost.airpost.mcp-http | airpost-mcp-http.service and .socket |
| Service plugin | com.airpost.airpost.service.<package> | airpost-service-<package>.service |
For another profile (--config-dir), the prefix gets a tag from the profile path: com.airpost.airpost.profile-<8 hex>.engine, airpost-profile-<8 hex>-engine. On Linux the systemd directory is $XDG_CONFIG_HOME/systemd/user when that’s set.
Each unit runs one binary by path and serves one profile, both written in it. Two copies of Airpost (the desktop’s and a package manager’s) share one set of units per profile; a unit running another copy’s binary belongs to that copy, install replaces it only with --replace, and airpost status names the owner.
<key>Label</key>
<string>com.airpost.airpost.engine</string>
<key>ProgramArguments</key>
<array>
<string>/path/to/airpost-engine</string>
<string>--mode</string>
<string>serve</string>
<string>--detached</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>CONFIG_DIR_PATH</key>
<string>/Users/you/Library/Application Support/Airpost</string>
</dict>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<dict>
<key>SuccessfulExit</key>
<false/>
</dict>
<key>ThrottleInterval</key>
<integer>10</integer>
The gateway and MCP plists hold their TCP port under Sockets instead of RunAtLoad.
Run airpost <engine|gateway|mcp-http> install --dry-run to see the exact units for your machine.
A dry run prints the binary, its SHA-256 and the unit, and writes nothing. On macOS, for a profile other than the default:
$ airpost engine install --dry-run --config-dir /tmp/airpost-test
Binary: /usr/local/bin/airpost-engine
SHA-256: 2b296d60357ba4f4a0f3dd0f76cd9831443cfe12d8dfe3e62d6e05998712a724
Unit /Users/you/Library/LaunchAgents/com.airpost.airpost.profile-9c402b50.engine.plist:
<?xml version="1.0" encoding="UTF-8"?>
...
<key>StandardOutPath</key>
<string>/tmp/airpost-test/launchd-engine.log</string>
...
Dry run: nothing written.
gateway install adds a URL: line (http://127.0.0.1:5180 by default) and, on Linux, the socket unit. After a real install the last line is one of:
Installed the engine unit; it starts at login or withairpost engine start“ when the desktop’s engine is running or--no-startwas given.Installed the gateway unit; it starts on the first connectionforgatewayandmcp-http.
With --json, install prints the same as a document (service, installed, load, started, manager, bin, sha256, name, path, text, socketUnit, socketText, url, port, onDemand). The command reference lists every subcommand’s shape.
Logs
airpost logs engine -f
airpost logs gateway
airpost logs mcp-http -n 100
| Log | macOS | Linux |
|---|---|---|
engine | <profile>/engine.log | <profile>/engine.log |
gateway, mcp-http | <profile>/launchd-<name>.log | journalctl --user -u <unit>.service -u <unit>.socket |
| An account | <profile>/engine-<accountId>.log | <profile>/engine-<accountId>.log |
| A service plugin | <profile>/services/<package>/service.log | the journal |
The launchd engine unit also writes its stdout and stderr to <profile>/launchd-engine.log. Account logs rotate to .log.1 up to .log.3; airpost logs -f follows across rotation.
Status
airpost status lists each service: installed, running, pid, unit, binary, owner, URL and warnings. airpost status --json has them under services; see JSON and scripting.
Remove everything
airpost uninstall
Removes every unit airpost installed for the profile (service plugins, mcp-http, the gateway, the engine) and the airpost link the desktop put on the PATH.
| Flag | Description |
|---|---|
--purge-profile | Also delete the profile: the mail cache, accounts and settings. |
-y, --yes | Don’t ask before deleting the profile. |
--unit-dir <DIR>, --no-load | As above. |
Troubleshooting
Related: The engine, MCP over HTTP, Self-hosting, status.