What a node is
The node is the only process that holds IMAP credentials, decrypts mail, evaluates grants, terminates TLS for its hostname, and serves/mcp + /papi.
Mental model: Node. Spec: Wire specification.
Path A — End-user Mac (recommended)
Users should install the macOS app, which bundles CPython +fedagent as
NodeRuntime and manages launchd.
- Build or obtain a DMG (Build the macOS client).
- Open the app → complete the setup wizard:
- Connect Gmail (app password)
- Register with a relay
- Obtain TLS for the node hostname
- Pair a phone
- Leave FAU on (stay-awake) while you expect agent traffic.
Verify
- Menu bar status green / idle sync
- Dashboard
GET /api/statusvia the app (loopback +X-FAU-Local) - Phone paired; optional Send test alert
- From another machine:
curl -sS https://<hostname>/.well-known/fau-node
Path B — Developer CLI (checkout)
Useful for hacking onnode/ without the Swift shell.
fedagent server /
runtime entrypoints used by launchd in the app). Prefer Path A for anything resembling
production.
Verify
Invariants you must not break
- Store encryption key sealed (Keychain) or explicitly marked insecure
- Dashboard API loopback only
- Tunnel: one live connection per
node_id - Approvals expire unanswered (deny-by-default product stance)
Failure modes
Next
- Pair phone: Build a mobile client or reference
apps/phone - Dashboard routes: Dashboard API
- Extend tools/policy: Extend the codebase