# LaunchAgents and LaunchDaemons

This page lists every launchd job that the repo installs, derived from the plist templates in `app-setup/templates/` and the plist heredocs in `app-setup/*.sh` and `scripts/server/*.sh`.

`<hostname>` is the lowercase server name (`SERVER_NAME` in [config keys](<https://smartwatermelon.github.io/mac-server-setup/reference/config-keys/index.md>)). `~operator` is the home folder of the operator account. `~admin` is the home folder of the admin account that runs the setup scripts.

## LaunchDaemons

LaunchDaemons live in `/Library/LaunchDaemons/` and start at boot, with or without a login. They run as root unless the plist sets `UserName`.

| Label | Runs as | What it runs | Schedule | Log path | Installed by | Plist source |
| --- | --- | --- | --- | --- | --- | --- |
| `com.caddyserver.caddy` | root | `/bin/bash /usr/local/bin/caddy-wrapper.sh`, which reads `CF_API_TOKEN` from the System keychain and starts Caddy | RunAtLoad; KeepAlive (restart on crash or on a non-zero exit); ThrottleInterval 30 s | `~operator/.local/state/caddy/caddy.log`, `~operator/.local/state/caddy/caddy-error.log` | [`app-setup/caddy-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/caddy-setup.sh>) | [`com.caddyserver.caddy.plist`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/templates/com.caddyserver.caddy.plist>) |
| `com.<hostname>.media-server` | operator (`UserName` in the plist) | `/usr/bin/python3 /usr/local/bin/media-server.py`, the file server behind `/media` | RunAtLoad; KeepAlive (always); ThrottleInterval 10 s | `~operator/.local/state/caddy/media-server.log` | [`app-setup/caddy-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/caddy-setup.sh>) | [`com.media-server.plist`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/templates/com.media-server.plist>) |
| `com.<hostname>.cloudflare-ddns` | root | `/bin/bash /usr/local/bin/cloudflare-ddns`, one DDNS update cycle | RunAtLoad; StartInterval 300 s | `~operator/.local/state/cloudflare-ddns.log` | [`app-setup/cloudflare-ddns-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/cloudflare-ddns-setup.sh>) | [`com.cloudflare-ddns.plist`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/templates/com.cloudflare-ddns.plist>) |
| `com.<hostname>.cloudflare-tunnel` | root | `/bin/bash /usr/local/bin/cloudflared-wrapper.sh`, which reads the tunnel token from the System keychain and starts `cloudflared` | RunAtLoad; KeepAlive (always); ThrottleInterval 30 s | `~operator/.local/state/cloudflared/cloudflared.log`, `~operator/.local/state/cloudflared/cloudflared-error.log` | [`app-setup/cloudflared-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/cloudflared-setup.sh>) | [`com.cloudflare-tunnel.plist`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/templates/com.cloudflare-tunnel.plist>) |
| `com.<hostname>.brew-upgrade` | admin (`UserName` in the plist) | `/bin/bash /usr/local/bin/<hostname>-brew-upgrade.sh`: `brew update`, formula upgrades, stable signing, cask upgrades, cleanup | StartCalendarInterval: daily at 04:30 | `~admin/.local/state/<hostname>-brew-upgrade-stdout.log`, `~admin/.local/state/<hostname>-brew-upgrade-stderr.log` | [`scripts/server/setup-auto-updates.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/scripts/server/setup-auto-updates.sh>) | Heredoc in `setup-auto-updates.sh` |
| `com.<hostname>.softwareupdate` | root | `/bin/bash /usr/local/bin/<hostname>-softwareupdate.sh`: `softwareupdate --download --all` (download only, no install) | StartCalendarInterval: Sundays at 04:00 | `/var/log/<hostname>-softwareupdate-stdout.log`, `/var/log/<hostname>-softwareupdate-stderr.log` | [`scripts/server/setup-auto-updates.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/scripts/server/setup-auto-updates.sh>) | Heredoc in `setup-auto-updates.sh` |

## LaunchAgents

LaunchAgents live in `~/Library/LaunchAgents/` of the account in the "Runs as" column. They start only when that account has a GUI login. The operator account logs in automatically at boot.

| Label | Runs as | What it runs | Schedule | Log path | Installed by | Plist source |
| --- | --- | --- | --- | --- | --- | --- |
| `com.<hostname>.operator-first-login` | operator | `~operator/.local/bin/operator-first-login.sh`, once. The script moves its own plist out of `LaunchAgents` when it finishes. | RunAtLoad | `~operator/.local/state/com.<hostname>.operator-first-login.log` | [`scripts/server/setup-application-preparation.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/scripts/server/setup-application-preparation.sh>) | Heredoc in `setup-application-preparation.sh` |
| `com.<hostname>.mount-nas-media` | admin and operator (one copy each) | `~/.local/bin/mount-nas-media.sh`, which mounts the NAS media share over NFS | RunAtLoad; StartInterval 120 s; KeepAlive while the last exit was non-zero; Aqua sessions only | `~/.local/state/com.<hostname>.mount-nas-media.log` | [`app-setup/plex-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/plex-setup.sh>) | Heredoc in `plex-setup.sh` |
| `com.<hostname>.plexmediaserver` | operator | `~operator/.local/bin/start-plex.sh`, which starts Plex Media Server | RunAtLoad; KeepAlive while the last exit was non-zero | `~operator/.local/state/<hostname>-plex-launchagent.log` | [`app-setup/plex-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/plex-setup.sh>) | Heredoc in `plex-setup.sh` |
| `com.<hostname>.plex-watchdog` | operator | `/bin/bash ~operator/.local/bin/plex-watchdog`, one poll of Plex settings against the golden config | RunAtLoad; StartInterval 300 s | `~operator/.local/state/plex-watchdog.log` | [`app-setup/plex-watchdog-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/plex-watchdog-setup.sh>) | Heredoc in `plex-watchdog-setup.sh` |
| `com.<hostname>.dropbox-sync` | operator | `~operator/.local/bin/start-rclone.sh`, the periodic rclone Dropbox sync | RunAtLoad; KeepAlive while the last exit was non-zero | `~operator/.local/state/com.<hostname>.dropbox-sync.log` | [`app-setup/rclone-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/rclone-setup.sh>) | Heredoc in `rclone-setup.sh` |
| `com.<hostname>.catch` | operator | `/Applications/Catch.app/Contents/MacOS/Catch` | RunAtLoad; no KeepAlive | None set | [`app-setup/catch-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/catch-setup.sh>) | Heredoc in `catch-setup.sh` |
| `com.<hostname>.podman-transmission-vm` | operator | `/bin/bash ~operator/.local/bin/podman-machine-start.sh`, which starts the Podman machine and supervises the Transmission container. It does not exit. | RunAtLoad; KeepAlive (always); ThrottleInterval 30 s | `~operator/.local/state/<hostname>-podman-vm-stdout.log`, `~operator/.local/state/<hostname>-podman-vm-stderr.log` | [`app-setup/podman-transmission-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/podman-transmission-setup.sh>) | Heredoc in `podman-transmission-setup.sh` |
| `com.<hostname>.transmission-trigger-watcher` | operator | `/bin/bash ~operator/.local/bin/transmission-trigger-watcher.sh`, which polls for completed-torrent trigger files and runs FileBot processing | RunAtLoad; KeepAlive (always) | `~operator/.local/state/<hostname>-trigger-watcher-stdout.log`, `~operator/.local/state/<hostname>-trigger-watcher-stderr.log` | [`app-setup/podman-transmission-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/podman-transmission-setup.sh>) | Heredoc in `podman-transmission-setup.sh` |
| `com.<hostname>.pending-move-cleanup` | operator | `/bin/bash ~operator/.local/bin/pending-move-cleanup.sh`, which removes processed folders from `pending-move/` | StartInterval 3600 s; RunAtLoad false | `~operator/.local/state/<hostname>-pending-move-cleanup.log` | [`app-setup/podman-transmission-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/podman-transmission-setup.sh>) | Heredoc in `podman-transmission-setup.sh` |
| `com.<hostname>.pia-port-watchdog` | operator | `/bin/bash ~operator/.local/bin/pia-port-watchdog.sh`, which alerts when PIA port forwarding is lost | StartInterval 900 s; RunAtLoad false | `~operator/.local/state/<hostname>-pia-port-watchdog.log` | [`app-setup/podman-transmission-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/podman-transmission-setup.sh>), only when `MONITORING_EMAIL` is set and msmtp is configured | Heredoc in `podman-transmission-setup.sh` |
| `com.<hostname>.stall-watchdog` | operator | `/bin/bash ~operator/.local/bin/stall-watchdog.sh`, which alerts on open TCC prompts, a `transmission-done` run longer than 45 minutes, and a failing or quiet supervisor | RunAtLoad; StartInterval 120 s | `~operator/.local/state/<hostname>-stall-watchdog.log` | [`app-setup/podman-transmission-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/podman-transmission-setup.sh>), only when `MONITORING_EMAIL` is set and msmtp is configured | Heredoc in `podman-transmission-setup.sh` |
| `com.<hostname>.access-policy-watchdog` | operator | `/bin/bash ~operator/.local/bin/access-policy-watchdog`, which emails when the Access or tunnel config drifts | RunAtLoad; StartInterval 900 s | `~operator/.local/state/access-policy-watchdog.log` | [`app-setup/access-policy-watchdog-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/access-policy-watchdog-setup.sh>) | [`com.access-policy-watchdog.plist`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/templates/com.access-policy-watchdog.plist>) |
| `com.<hostname>.tunnel-watchdog` | operator | `/bin/bash ~operator/.local/bin/tunnel-watchdog`, which checks the `cloudflared` `/ready` endpoint and emails after 3 failed checks | RunAtLoad; StartInterval 60 s | `~operator/.local/state/tunnel-watchdog.log` | [`app-setup/tunnel-watchdog-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/tunnel-watchdog-setup.sh>) | [`com.tunnel-watchdog.plist`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/templates/com.tunnel-watchdog.plist>) |
| `com.<hostname>.tvmaze-scrobble` | operator | `/usr/bin/python3 ~operator/.local/bin/tvmaze-scrobble-listener --port <TVMAZE_SCROBBLE_PORT> --worker ~operator/.local/bin/tvmaze-scrobble`, the Plex webhook listener | RunAtLoad; KeepAlive (always); ThrottleInterval 30 s | `~operator/.local/state/tvmaze-scrobble.log` | [`app-setup/tvmaze-scrobble-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/tvmaze-scrobble-setup.sh>) | [`com.tvmaze-scrobble.plist`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/templates/com.tvmaze-scrobble.plist>) |
| `com.<hostname>.tvmaze-reconcile` | operator | `/bin/bash ~operator/.local/bin/tvmaze-scrobble --reconcile`, which syncs plays that the webhook missed | RunAtLoad; StartInterval 3600 s | `~operator/.local/state/tvmaze-scrobble.log` | [`app-setup/tvmaze-scrobble-setup.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/tvmaze-scrobble-setup.sh>) | [`com.tvmaze-reconcile.plist`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/app-setup/templates/com.tvmaze-reconcile.plist>) |

## Jobs that Homebrew installs

The repo does not write these plists. It runs `brew services start logrotate`, and Homebrew writes its own LaunchAgent.

| Service | Runs as | Started by |
| --- | --- | --- |
| `logrotate` (Homebrew service) | admin | [`scripts/server/setup-log-rotation.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/scripts/server/setup-log-rotation.sh>) |
| `logrotate` (Homebrew service) | operator | [`scripts/server/operator-first-login.sh`](<https://github.com/smartwatermelon/mac-server-setup/blob/main/scripts/server/operator-first-login.sh>) |

## Related pages

- [Monitoring](<https://smartwatermelon.github.io/mac-server-setup/components/monitoring/index.md>): the watchdogs and their alert email.
- [Caddy](<https://smartwatermelon.github.io/mac-server-setup/components/caddy/index.md>) and [Cloudflare Tunnel](<https://smartwatermelon.github.io/mac-server-setup/components/cloudflare-tunnel/index.md>): the web front end daemons.
- [Logs](<https://smartwatermelon.github.io/mac-server-setup/reference/logs/index.md>): every log file, including the logs that scripts write themselves.
