feat(server): run the background service on macOS via launchd

[t3dotgg]

Wanted the T3 Connect/serve daemon running in the background on a Mac, the same way it works on Linux. But `t3 service install` was systemd-only and failed closed on darwin.

Now macOS gets a per-user LaunchAgent (`~/Library/LaunchAgents/com.t3tools.t3code.service.plist`). The pinned runtime, stable launcher, and remote-update protocol are reused unchanged; only the service-manager layer is new. The platform split is a small data-driven `BootServiceManager` (paths, pure renderer, command steps), so install/uninstall/status stay single-flow with no platform branches. launchctl steps that fail on already/not-loaded states are tolerated; the final `kickstart -k` stays strict so a broken setup fails loudly.

Honest semantics: a LaunchAgent starts at login and stops at logout (no linger equivalent), so onboarding copy and docs say so instead of promising boot-time behavior.

Verified end to end on an M-series Mac with an isolated `T3CODE_HOME`: install pins `t3@0.0.33` from npm, the job runs, killing the launcher gets respawned by KeepAlive, the child server carries the launcher IPC context (so remote self-update capability is advertised), and uninstall removes the job and plist cleanly. 28 tests pass across the touched files.

---

Built by Claude Code (Fable 5) with human direction from Theo.

---

Note

Medium Risk
Touches host service installation and long-blocking launchctl/systemctl orchestration; mistakes could leave a broken or stale agent, though behavior is heavily tested and Linux paths are mostly refactored, not rewritten.

Overview
macOS can now install the same pinned-launcher background service via a per-user LaunchAgent (~/Library/LaunchAgents/com.t3tools.t3code.service.plist). Linux systemd behavior is unchanged; Windows still fails closed.

bootService is refactored around a BootServiceManager abstraction: each platform supplies paths, a pure unit/plist renderer, and declarative launchctl / systemctl step lists consumed by shared install / uninstall / status flows. macOS uses bootout --wait, optional enable/bootout steps, 120s stop timeouts (above systemd/ExitTimeOut), and plist settings aligned with the existing launcher/update model. HostProcessUserId (process.getuid() on POSIX) drives the gui/<uid> launchd domain.

Onboarding and status copy no longer promise post-logout reachability on Mac: connect and service prompts describe login-scoped availability instead of boot/linger behavior. User and internal docs now document Linux vs macOS differences (SSH install, TCC, Login Items).

^{Reviewed by Cursor Bugbot for commit d3db140. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add macOS launchd support for the background boot service

• Adds a launchdManager in bootService.ts that installs a launch agent plist, bootstraps it at login, and handles stop/restart/uninstall via launchctl.
• Adds renderBootServicePlist to generate a launchd plist with RunAtLoad, KeepAlive, ThrottleInterval=5, ExitTimeOut=90, and consolidated stdout/stderr logging.
• Refactors the boot service factory to select between systemd (Linux) and launchd (macOS) via a new selectBootServiceManager abstraction, using a new HostProcessUserId context for POSIX uid.
• Updates CLI messaging and onboarding prompts to reflect macOS login-scoped persistence vs. Linux boot-time/linger persistence.
• Behavioral Change: on macOS the service runs only while the user is logged in (no linger equivalent); Windows remains unsupported.

^{Macroscope summarized d3db140.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3cdab0e2-46d3-4cd5-817a-95c4e2704be1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.3 KiB	12.6 KiB	+1.3 KiB (+11.3%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	6.3 KiB	+848 B (+15.2%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	6.3 KiB	+468 B (+7.8%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	51.8 KiB	+2.1 KiB (+4.2%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.3 KiB	12.6 KiB	+1.3 KiB (+11.2%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	6.3 KiB	+812 B (+14.5%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.9 KiB	6.3 KiB	+490 B (+8.2%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	52.7 KiB	+2.1 KiB (+4.2%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: 5a84614 · PR result: d3db140 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 99.9 KiB
• Claude decoded thread snapshot: 100.6 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces new macOS launchd support for the background service—a significant new feature with new platform integration logic. There is also an open Medium-severity finding about potential bootout compatibility issues on older macOS versions.

^{You can add or adjust custom eligibility rules. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d3db140. Configure here.}

[cursor]

Optional bootout skips stop without --wait

Medium Severity

launchctl bootout --wait is not available before macOS 26, but stop and uninstall still mark that step optional. An unrecognized flag fails the command without unloading the job, the failure is ignored, and install then rewrites launcher and state under a still-running agent, after which bootstrap fails. Updates and reinstalls on Sequoia-era Macs never stop the existing service.

Additional Locations (1)

• apps/server/src/cloud/bootService.ts#L329-L337

 

^{Reviewed by Cursor Bugbot for commit d3db140. Configure here.}

[Albro3459]

@t3dotgg this breaks T3 Connect auth for me on ARM MacOS 26.5.

Connect was setup and linked and status was green:

npx t3@0.0.34-nightly.20260819.1133 connect status

Then, I ran npx t3@0.0.34-nightly.20260819.1133 service install and npx t3@0.0.34-nightly.20260819.1133 service status.

It started T3 correctly, but Connect couldn't auth with cloudflared:

<user>@<machine>:~ % ps aux | rg '[c]loudflared'
<user>@<machine>:~ % tail -n 200 ~/.t3/userdata/logs/boot-service.log | \
  rg -i 'relay|cloudflared|tunnel|warning|error|failed'
    cause: 'RelayAuthInvalidError: Relay authentication failed: not_authorized\n' +
      '    at AgentAwarenessRelay.publishThread (file:///Users/<user>/.t3/runtime/versions/0.0.34-nightly.20260819.1133/node_modules/t3/dist/bin.mjs:175637:6)'
[10:30:19.883] WARN (#248): agent activity publish failed
    cause: 'RelayAuthInvalidError: Relay authentication failed: not_authorized\n' +
    ...