Skip to main content
Purpose: produce a working macOS supervisor (menu bar + NodeRuntime + launchd). Audience: developers changing apps/macos/ or cutting DMGs.

What this client is

A thin Swift shell. It does not sync mail or evaluate grants. It installs the bundled node, seals keys, shows pair QR, and talks to loopback /api/*. Architecture: macOS client. Dashboard contract: Dashboard API.

Prerequisites

  • macOS 14+
  • Swift 5.9+ (Xcode 15+ recommended for full toolchain)
  • For distribution: Apple Developer ID + notary profile

1. Build the app bundle

NodeRuntime (CPython + fedagent) is bundled by default. Set SKIP_NODE_RUNTIME=1 only for Swift-only iteration.

2. Run tests

3. Make a local DMG

Ad-hoc signed → this Mac only. Gatekeeper: right-click → Open. Notarized builds: set FAU_TEAM_ID / FAU_SIGN_IDENTITY and run without --skip-sign.

4. Verify

  1. App launches; menu bar item appears.
  2. Wizard can reach loopback status API.
  3. After Gmail + relay: pair QR uses relay hostname (not 127.0.0.1).
  4. FAU off restores sleep (stay-awake reverted).

Invariants

  • Never put FAU_HOME / runtime under Documents, Desktop, or Downloads
  • Never call /papi or /mcp from the Mac app as a device/agent
  • Uninstall scripts must remain safe (scripts/uninstall.sh)

Next