What this is
The macOS app is a native supervisor and setup UX for the node. It does not sync mail, evaluate grants, or implement MCP. Mental model: an installer + status light + pairing QR generator glued to a loopback HTTP admin API. Source:apps/macos/ (FAUKit library + FAUMenuBar UI).
Goals
- Let a non-developer install FAU without touching Python.
- Keep the node alive across login (launchd).
- Seal the store key in Keychain / Secure Enclave.
- Optionally keep the Mac reachable while FAU is on (stay-awake).
- Show pairing material phones can scan.
Non-goals
- Being the daily approval surface (that is the phone).
- Re-implementing policy in Swift.
- Exposing the dashboard token off the machine.
Architecture
Invariant: FAU home, runtime, and working directories must not be under
Documents/Desktop/Downloads. TCC will otherwise ask for permissions in loops or fail
silently for launchd children.
Lifecycle
State
APIs consumed
Only dashboard routes (see Dashboard API). Examples: status, pause, pair/start, devices, settings, test-gmail, test-push, approvals decide, audit. Must not call/papi/* or /mcp as if it were a phone or agent.
Pairing flow
- Ensure relay hostname / TLS ready (phone cannot use
127.0.0.1). GET /api/pair/start→ six-digit code + QR payload.- Payload:
fau://pair?host=<host>&code=<6 digits>&fp=<fingerprint>. - Phone completes
POST /papi/pair.
Stay-awake
While FAU is enabled, the app may disable sleep so agents can reach the node. Turning FAU off must restore priorpmset behavior.
Unusual condition: first lid-close after disabling stay-awake can feel like a long /
choppy wake — that is often the first real sleep after disablesleep, not a GPU bug.
Do not “fix” with permanent disable-sleep.
Build / distribute
FAU_TEAM_ID / FAU_SIGN_IDENTITY.Runtime: macOS 14+. End users need neither Xcode nor system Python.
Failure modes
3 AM checklist
- Is
Federated Agent Use/ node process running? curl -sS -H "X-FAU-Local: $(cat \"$HOME/Library/Application Support/FAU/local_token\")" http://127.0.0.1:8765/api/status- Relay connected? Dashboard relay fields /
fedagent relay status - Disk space on FAU home volume
- Reinstall runtime only after backing up / understanding data wipe scripts
Extending
Design decisions
Decision: thin Swift shell + Python node.Why: crypto/mail/policy iterate faster in Python; Mac-only chores stay native.
Tradeoff: two languages; packaging NodeRuntime into the app. Decision: loopback dashboard token.
Why: powerful admin without exposing it on the relay.
Tradeoff: any local malware as the user can admin the node — accepted; documented in security model.