# 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.