fidelity-ai-workspace/core/services/macos-installation-model.md

macOS Installation Model

How production macOS utilities commonly do it

Apps such as Cloudflare WARP, VPN clients, Docker Desktop, and device agents usually separate:

• a user-facing app or menu bar app;
• one or more background services;
• launchd configuration for automatic startup;
• privileged helpers only when system-level networking, drivers, packet filtering, or protected paths are required.

Common mechanisms:

• LaunchAgent in ~/Library/LaunchAgents for per-user background/login startup.
• LaunchDaemon in /Library/LaunchDaemons for root/system services.
• SMAppService / login items for sandboxed or App Store-aligned apps.
• Privileged helper tools via SMJobBless when admin-level installation is required.
• .pkg installers when the install needs privileged locations, daemons, receipts, or managed deployment.

Recommended AI Workspace approach

Use a staged model:

1. Current local developer install

   • Build a real .app bundle into apps/mac/AIWorkspace/dist/.
   • Install to ~/Applications/AIWorkspace.app.
   • Install a per-user LaunchAgent for start at login.

2. Production-ready local install

   • Keep using a per-user LaunchAgent because services are local user tools and do not require root.
   • Add a one-step installer script that builds, installs, optionally enables start at login, and opens the app.
   • Avoid privileged helpers until a real system-level requirement appears.

3. Future polished distribution

   • Create a signed/notarized .app or .pkg.
   • Consider SMAppService for login item management from inside the app.
   • Add a small daemon API if the UI needs richer lifecycle control than shelling out to services.py.

Why not LaunchDaemon now

The current services are user-context services:

• Mattermost Desktop launching must happen in the user's GUI session.
• Photo Inbox writes to user-owned folders and uses clipboard/notifications.
• The MCP and proxy bind localhost ports and do not require root.

A root daemon would add unnecessary permission prompts and security risk. A per-user LaunchAgent is the correct production-leaning step for this stage.