Skip to main content

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

  1. Ensure relay hostname / TLS ready (phone cannot use 127.0.0.1).
  2. GET /api/pair/start → six-digit code + QR payload.
  3. Payload: fau://pair?host=<host>&code=<6 digits>&fp=<fingerprint>.
  4. Phone completes POST /papi/pair.
If pair start would emit loopback, refuse — a phone on cellular cannot reach it.

Stay-awake

While FAU is enabled, the app may disable sleep so agents can reach the node. Turning FAU off must restore prior pmset 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

Notarized Developer ID builds need FAU_TEAM_ID / FAU_SIGN_IDENTITY.
Runtime: macOS 14+. End users need neither Xcode nor system Python.

Failure modes

3 AM checklist

  1. Is Federated Agent Use / node process running?
  2. curl -sS -H "X-FAU-Local: $(cat \"$HOME/Library/Application Support/FAU/local_token\")" http://127.0.0.1:8765/api/status
  3. Relay connected? Dashboard relay fields / fedagent relay status
  4. Disk space on FAU home volume
  5. 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.