launchd.md

macOS 로그인 시 Controller 자동 실행 (launchd)

등록은 사용자가 직접 수행한다 (앱이 시스템 설정을 건드리지 않는다).

1. 아래 예시의 /Users/you/projects/agent-deck을 실제 저장소 절대 경로로 바꾼 뒤 ~/Library/LaunchAgents/com.example.agent-deck.plist를 생성한다. 실제 경로가 들어간 plist는 Git에 추가하지 않는다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.example.agent-deck</string>
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/node</string>
    <string>/Users/you/projects/agent-deck/server/src/index.ts</string>
  </array>
  <key>WorkingDirectory</key><string>/Users/you/projects/agent-deck</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/Users/you/.agent-deck/controller.out.log</string>
  <key>StandardErrorPath</key><string>/Users/you/.agent-deck/controller.err.log</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/Users/you/.local/bin</string>
  </dict>
</dict>
</plist>

2. 로드:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.agent-deck.plist

해제:

launchctl bootout gui/$(id -u)/com.example.agent-deck

주의:

• launchd 환경은 PATH 가 최소라서 EnvironmentVariables.PATH 를 반드시 지정한다 (tmux·codex·claude·devtunnel 탐색용).
• SSH 프로필 사용 시: launchd 로 뜬 Controller 에는 SSH_AUTH_SOCK(ssh-agent)이 없어 키 암호가 걸린 키는 인증에 실패할 수 있다. 해결책 중 하나를 쓴다:
  • macOS 키체인에 키를 저장 (ssh-add --apple-use-keychain) + ~/.ssh/config 에 UseKeychain yes — launchd 환경에서도 동작
  • 해당 호스트 전용의 암호 없는 키 사용
  • 참고: pane 의 환경은 tmux 서버에서 상속되므로, tmux 서버를 로그인 셸에서 먼저 띄워 두면 agent 소켓이 살아 있는 경우도 있다 (신뢰하지는 말 것)
• stdout 로그에는 Tunnel URL·QR 만 출력된다. 비밀정보는 출력되지 않는다.
• devtunnel 인증이 만료되면 Controller가 GitHub 브라우저 로그인을 실행함. 브라우저가 열리지 않으면 로컬 터미널에서 devtunnel user login -g를 실행함. 성공 후 Controller 재시작은 필요 없음.
• Controller 가 죽어도 tmux 세션은 tmux 서버 소유라서 계속 살아 있고, 재시작 시 자동 재발견된다.