Airpost
Background services

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.

CommandRunsStarts
airpost engineairpost-engine --mode serve --detachedAt login, and again after a failed exit.
airpost gatewayairpost-gateway serveOn the first connection to its port.
airpost mcp-httpairpost-mcp httpOn the first connection to its port.
airpost serviceA service plugin’s programAfter the engine.

Subcommands

engine, gateway and mcp-http share these subcommands:

SubcommandDescription
installWrite the unit and load it.
uninstallStop the unit and remove it.
startStart the installed unit’s program if it isn’t running.
stopStop it until the next login or start.
restartRestart it, so it runs the binary now at its path. Run this after an upgrade.

gateway also has pair, below.

Flags for every subcommand

FlagDescription
--unit-dir <DIR>Write the units here instead of ~/Library/LaunchAgents or ~/.config/systemd/user, and load nothing. Env: AIRPOST_UNIT_DIR.
--no-loadWrite the units but don’t load or start them.

Flags for install

Flagenginegatewaymcp-httpDescription
--bin <PATH>yesyesyesThe binary. Default: the one beside airpost, or AIRPOST_ENGINE_BIN, AIRPOST_GATEWAY_BIN, AIRPOST_MCP_BIN.
--key-file <PATH>yesKeep 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>yesWhere the gateway listens. Default 127.0.0.1:5180.
--web-root <DIR>yesThe built web client. Default: one beside the gateway binary (airpost-web, web or ../share/airpost/web).
--public-url <URL>yesWhere browsers reach the gateway when it isn’t the bind address, e.g. behind a TLS proxy.
--port <PORT>yesThe port. Default: http.port in mcp.json.
--replaceyesyesyesTake over a unit that runs another copy of Airpost’s binaries (the desktop’s, or a package manager’s).
--no-startyesyesyesEnable the unit for login but don’t start it now.
--dry-runyesyesyesPrint 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).

FlagDescription
--adminGrant 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.

SubcommandDescription
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 listThe installed services: source, binary, hash and unit.

service install flags, besides --unit-dir and --no-load:

FlagDescription
--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-runPrint 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:

UnitmacOS label (~/Library/LaunchAgents/<label>.plist)systemd unit (~/.config/systemd/user/)
Enginecom.airpost.airpost.engineairpost-engine.service
Gatewaycom.airpost.airpost.gatewayairpost-gateway.service and .socket
MCP HTTPcom.airpost.airpost.mcp-httpairpost-mcp-http.service and .socket
Service plugincom.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 with airpost engine start“ when the desktop’s engine is running or --no-start was given.
  • Installed the gateway unit; it starts on the first connection for gateway and mcp-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
LogmacOSLinux
engine<profile>/engine.log<profile>/engine.log
gateway, mcp-http<profile>/launchd-<name>.logjournalctl --user -u <unit>.service -u <unit>.socket
An account<profile>/engine-<accountId>.log<profile>/engine-<accountId>.log
A service plugin<profile>/services/<package>/service.logthe 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.

FlagDescription
--purge-profileAlso delete the profile: the mail cache, accounts and settings.
-y, --yesDon’t ask before deleting the profile.
--unit-dir <DIR>, --no-loadAs above.

Troubleshooting

Related: The engine, MCP over HTTP, Self-hosting, status.