macOS (launchd)

apus gateway install
apus gateway status
apus gateway restart
apus gateway stop

Use apus gateway restart for restarts. Do not chain apus gateway stop and apus gateway start as a restart substitute.

On macOS, gateway stop uses launchctl bootout and verifies that the LaunchAgent is unloaded and its process has exited before reporting success. This removes the LaunchAgent from the current boot session without persisting a disable, so KeepAlive auto-recovery still works after unexpected crashes and gateway start re-enables cleanly. To also persistently suppress auto-respawn across reboots, pass --disable: apus gateway stop --disable.

If shutdown cannot be verified, the command fails with the exact launchctl bootout gui/<uid>/<label> command to run from an external terminal in the service owner's logged-in macOS session. A free Gateway port alone does not prove that the service is stopped.

LaunchAgent labels are ai.apus.gateway (default) or ai.apus.<profile> (named profile). apus doctor audits and repairs service config drift.

On macOS, service restarts preserve multiline environment values, including PEM keys, embedded quotes, and trailing newlines. If an older restart already truncated a value in the generated service environment, another restart cannot reconstruct it. Restore the complete value in its authored configuration or environment and reinstall with apus gateway install --force.

Existing system LaunchDaemons

Apus installs and manages a per-user LaunchAgent. It does not install or manage system LaunchDaemons. If a custom LaunchDaemon already uses the same gateway label, Apus refuses to write, start, restart, or repair a user LaunchAgent because two KeepAlive managers can repeatedly restart the same gateway.

The ownership check reads launchctl print system/<label> and also checks installed plists under /Library/LaunchDaemons. It fails closed when system ownership cannot be verified, and --force does not bypass it. apus gateway status reports a loaded same-label system job; add --deep to scan installed system service files.

The runtime and standalone updater parse captured plist bytes with the native parser. If endpoint protection denies pathname parsing during a detached restart, its ownership scan tries a bounded read and parses the captured bytes instead. Actual permission-denied reads are skipped, while malformed data and other read failures still block activation. Loaded same-label jobs remain blocked; an unloaded same-label plist hidden by read denial cannot be detected. The detached restart fallback uses macOS's /usr/bin/perl; if that reader is unavailable, the scan still refuses unverifiable activation. This does not change endpoint-protection policy or suppress its alerts.

Choose one lifecycle owner before retrying:

• To keep the custom system LaunchDaemon, remove any competing user LaunchAgent and set APUS_SERVICE_REPAIR_POLICY=external when running Doctor so it remains diagnostic-only for service lifecycle.
• To return to the supported user LaunchAgent, unload the system job with sudo launchctl bootout system/<label>, remove or relocate its actual plist, sign in to the macOS desktop as the target user, then run apus gateway install.

For the default profile, <label> is ai.apus.gateway. Named profiles use ai.apus.<profile>.

Linux (systemd user)

apus gateway install
systemctl --user enable --now apus-gateway[-<profile>].service
apus gateway status

For persistence after logout, enable lingering:

sudo loginctl enable-linger $(whoami)

On a headless server without a desktop session, also make sure XDG_RUNTIME_DIR is set (export XDG_RUNTIME_DIR=/run/user/$(id -u)) before retrying systemctl --user commands.

Service inspection preserves an explicit DBUS_SESSION_BUS_ADDRESS that reaches the user manager. Otherwise it tries $XDG_RUNTIME_DIR/bus, then the private manager socket for inspection. Install, status, and update admission reuse the selected route; gateway status --deep shows it. Update admission rechecks routes that timed out during earlier discovery. A socket's existence alone does not replace a working custom bus. If no route reaches the manager, check XDG_RUNTIME_DIR, log in once or enable lingering, and verify systemctl --user status. On Debian/Ubuntu, dbus-user-session provides the user bus; start it with systemctl --user start dbus.socket if needed. An absent unit is safe to install; an unreadable existing definition must be repaired by its owner first.

Manual user-unit example when you need a custom install path:

[Unit]
Description=Apus Gateway
After=network-online.target
Wants=network-online.target
StartLimitBurst=10
StartLimitIntervalSec=300

[Service]
ExecStart=/usr/local/bin/apus gateway --port 18789
Restart=always
RestartSec=5
RestartPreventExitStatus=78
TimeoutStopSec=330
TimeoutStartSec=30
SuccessExitStatus=0 143
OOMPolicy=continue
KillMode=mixed

[Install]
WantedBy=default.target

TimeoutStopSec=330 covers the Gateway's maximum 315-second stop drain plus a 15-second cleanup and exit margin. The Gateway clamps its drain to the installed unit's effective stop timeout; see Systemd stop deadlines. To inspect the current managed unit body, run systemctl --user cat apus-gateway.service (or systemctl --user cat apus-gateway-<profile>.service for a named profile).

Windows (native)

apus gateway install
apus gateway status --json
apus gateway restart
apus gateway stop

Native Windows managed startup uses a Scheduled Task named Apus Gateway (or Apus Gateway (<profile>) for named profiles). If Scheduled Task creation is denied, Apus falls back to a per-user Startup-folder launcher that points at gateway.cmd inside the state directory.

Linux (system service)

Use a system unit for multi-user/always-on hosts.

Start with the user-unit example, install it under /etc/systemd/system/apus-gateway[-<profile>].service, adjust ExecStart= if your apus binary lives elsewhere, and add User= to its [Service] section:

[Service]
User=<user>

Replace <user> with the non-root account that owns the Apus state and configuration. A system unit without User= runs as root. Running the Gateway and its agent commands as root is unsafe and unsupported for this setup.

When Group= is omitted, systemd uses the selected account's primary group. By default, User= also supplies that account's HOME, which Apus uses for normal state and configuration lookup. For intentional custom locations, set APUS_STATE_DIR and APUS_CONFIG_PATH in the unit environment. Do not copy configuration into root's home as a workaround. On a single-user host, the user unit above with loginctl enable-linger is the supported way to keep the Gateway running without a login session.

Do not also let apus doctor --fix install a user-level gateway service for the same profile/port. Doctor refuses that automatic install when it finds a system-level Apus gateway service; use APUS_SERVICE_REPAIR_POLICY=external when the system unit owns the lifecycle.

apus gateway status --deep inspects the installed system unit and reports systemd system. Run Doctor from the non-root User= account with the same state and config paths. For offline repair, stop the unit through its system service owner first, run apus doctor --fix, then start the unit through that owner. Doctor can verify a stopped system unit without rewriting its definition or creating a competing user service. An unavailable manager or an unverified service account still blocks maintenance.

After writing the unit, reload systemd and enable it:

sudo systemctl daemon-reload
sudo systemctl enable --now apus-gateway[-<profile>].service