Domínios do launchd: escolher entre LaunchAgent e LaunchDaemon e carregá-lo com o launchctl

Objetivo

Instalar um programa que o macOS inicia automaticamente — no login do usuário (um LaunchAgent) ou na inicialização, sem sessão de usuário (um LaunchDaemon) — e gerenciá-lo com os subcomandos modernos do launchctl, em vez do par obsoleto load/unload.

Pré-requisitos

Uma sessão de Terminal; um programa referenciado por caminho absoluto; direitos de administrador/sudo apenas para o que for instalado fora do seu próprio diretório home. macOS 13 Ventura ou posterior (bootstrap/bootout/kickstart são a interface recomendada desde o OS X 10.10, então os comandos também funcionam em versões mais antigas).

Passos

1. Escolha o domínio. Um LaunchAgent roda dentro da sessão de um usuário específico e pode acessar a interface gráfica; ele pertence ao domínio gui/<uid> (login interativo) ou user/<uid> (segundo plano, sem GUI). Um LaunchDaemon roda como root, sem contexto de usuário, e pertence ao domínio system.
2. Escolha o caminho. ~/Library/LaunchAgents não exige direitos de administrador e vale apenas para aquele usuário. /Library/LaunchAgents é instalado por um administrador, mas ainda assim roda como o usuário que fizer login. /Library/LaunchDaemons é instalado por um administrador e roda como root, independentemente de quem estiver logado. /System/Library/LaunchAgents e /System/Library/LaunchDaemons são reservados à Apple e ficam no Signed System Volume; nunca adicione arquivos ali.
3. Escreva o plist com, no mínimo, um Label único em formato DNS reverso, um array ProgramArguments (não uma string de shell) e RunAtLoad, KeepAlive ou StartInterval.
4. Valide antes de carregar: plutil -lint /Library/LaunchDaemons/com.example.worker.plist.
5. Para um daemon, defina o proprietário: sudo chown root:wheel e sudo chmod 644 no plist.
6. Carregue-o: sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.worker.plist (daemon) ou launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.agent.plist (agent, executado como esse usuário, sem sudo).
7. A persistência vem da localização do arquivo: o launchd carrega todos os plists de /Library/LaunchDaemons na inicialização e todos os plists dos diretórios LaunchAgents no login. launchctl enable system/com.example.worker apenas remove uma substituição de desativado (definida com launchctl disable, que também persiste após reinicializações); launchctl print-disabled system lista essas substituições.
8. Inicie-o agora ou reinicie uma instância em execução: launchctl kickstart -k system/com.example.worker.
9. Para removê-lo: sudo launchctl bootout system/com.example.worker antes de apagar o arquivo plist.

Resultado esperado

launchctl print system/com.example.worker (ou o alvo gui/<uid>/... correspondente, no caso de um agent) mostra state = running, o PID e o último status de saída; um job que não está carregado exibe, em vez disso, "Could not find service".

Limites e base de verificação

Os papéis dos diretórios e a divisão por domínio vêm da nota técnica da Apple sobre daemons e agents; a sintaxe atual dos subcomandos bootstrap/bootout/enable/kickstart/print não é publicada pela Apple como página web e foi extraída de uma referência de comandos. O par legado launchctl load -w/unload -w ainda funciona no macOS atual, mas não expõe os erros da fase de bootstrap da mesma forma e não é a interface documentada; prefira bootstrap/bootout em scripts novos. Nem bootstrap nem bootout exigem reinicialização para ter efeito.