Skip to main content
Purpose: get a node online so agents can reach it and a phone can approve. Audience: developers operating FAU for themselves or packaging it for users.

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. Users should install the macOS app, which bundles CPython + fedagent as NodeRuntime and manages launchd.
  1. Build or obtain a DMG (Build the macOS client).
  2. Open the app → complete the setup wizard:
    • Connect Gmail (app password)
    • Register with a relay
    • Obtain TLS for the node hostname
    • Pair a phone
  3. Leave FAU on (stay-awake) while you expect agent traffic.

Verify

  • Menu bar status green / idle sync
  • Dashboard GET /api/status via 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 on node/ without the Swift shell.
Register with a relay (after Gmail is configured in config / wizard equivalent):
Start the HTTP/MCP stack the way your checkout scripts document (fedagent server / runtime entrypoints used by launchd in the app). Prefer Path A for anything resembling production.

Verify

Optional Apple EventKit helper (Calendar/Reminders):

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