launchd domains: choosing a LaunchAgent or LaunchDaemon and loading it with launchctl

Goal

Install a program that macOS starts automatically — at user login (a LaunchAgent) or at boot with no user session (a LaunchDaemon) — and manage it with the modern launchctl subcommands instead of the deprecated load/unload pair.

Prerequisites

A Terminal session; a program referenced by an absolute path; admin/sudo rights only for anything installed outside your own home directory. macOS 13 Ventura and later (bootstrap/bootout/kickstart have been the recommended interface since OS X 10.10, so the commands also work on older releases).

Steps

1. Pick the domain. A LaunchAgent runs inside a specific user's session and can reach the GUI; it belongs in the gui/<uid> (interactive login) or user/<uid> (background, no GUI) domain. A LaunchDaemon runs as root with no user context and belongs in the system domain.
2. Pick the path. ~/Library/LaunchAgents needs no admin rights and applies to that user only. /Library/LaunchAgents is admin-installed but still runs as whichever user logs in. /Library/LaunchDaemons is admin-installed and runs as root regardless of who is logged in. /System/Library/LaunchAgents and /System/Library/LaunchDaemons are reserved for Apple and sit on the Signed System Volume; never add files there.
3. Write the plist with, at minimum, a unique reverse-DNS Label, a ProgramArguments array (not a shell string), and RunAtLoad, KeepAlive or StartInterval.
4. Validate before loading: plutil -lint /Library/LaunchDaemons/com.example.worker.plist.
5. For a daemon, set ownership: sudo chown root:wheel and sudo chmod 644 on the plist.
6. Load it: sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.worker.plist (daemon), or launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.agent.plist (agent, run as that user, no sudo).
7. Persistence comes from the file location: launchd loads every plist in /Library/LaunchDaemons at boot and every plist in the LaunchAgents directories at login. launchctl enable system/com.example.worker only clears a disabled override (set with launchctl disable, which also survives reboots); launchctl print-disabled system lists those overrides.
8. Start it now, or restart a running instance: launchctl kickstart -k system/com.example.worker.
9. To remove it: sudo launchctl bootout system/com.example.worker before deleting the plist file.

Expected result

launchctl print system/com.example.worker (or the matching gui/<uid>/... target for an agent) shows state = running, the PID and the last exit status; a job that isn't loaded prints "Could not find service" instead.

Limits and test basis

Directory roles and the per-domain split come from Apple's technical note on daemons and agents; the current bootstrap/bootout/enable/kickstart/print subcommand syntax is not published by Apple as a web page and is taken from a command reference. The legacy launchctl load -w/unload -w pair still runs on current macOS but does not surface bootstrap-time errors the same way and is not the documented interface; prefer bootstrap/bootout in new scripts. Neither bootstrap nor bootout requires a reboot to take effect.