> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# macOS client

> Menu bar supervisor — NodeRuntime, launchd, Keychain, pairing, stay-awake, and safe modification.

## 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

```mermaid theme={null}
flowchart LR
  UI[FAUMenuBar SwiftUI]
  KIT[FAUKit]
  API[Node /api loopback]
  LD[launchd]
  NR[NodeRuntime CPython]
  UI --> KIT
  KIT --> API
  KIT --> LD
  LD --> NR
  NR --> API
```

| Module | Responsibility |
| - | - |
| `NodeClient` | Typed HTTP to `127.0.0.1:8765` with `X-FAU-Local` |
| `LaunchdController` | Install/start/stop `com.fau.node` |
| `StoreKeySealer` | Seal/unseal store master key |
| `StayAwakeController` | `pmset` assertions; restore on FAU off |
| `PairingPayload` | Build/parse `fau://pair?…`, QR rendering |
| `StatusPoller` | Menu bar state with backoff |

**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

| Phase | What happens |
| - | - |
| Install | Copy app; first launch runs wizard |
| Wizard | Gmail → relay register → TLS → pair phone → done |
| Steady | Menu status; optional dashboard WebView |
| FAU off | Pause agents + **revert** stay-awake |
| Uninstall | Stop launchd; remove app; optional delete `Application Support/FAU` |

## State

| State | Owner | Notes |
| - | - | - |
| `X-FAU-Local` token | Node writes; app reads from FAU home | Loopback only |
| launchd plist | App installs | Points at bundled runtime |
| Keychain items | App + node conventions | Store key material |
| UI preferences | App | Not security-critical |

## APIs consumed

Only **dashboard** routes (see [Dashboard API](https://docs.fau.run/developer/protocol/dashboard.md)). 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

```bash theme={null}
cd apps/macos
bash scripts/build-app.sh
bash scripts/build-dmg.sh --skip-sign --download   # ad-hoc, this Mac
```

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

## Failure modes

| Failure | Symptom | Debug |
| - | - | - |
| Node not starting | Amber/red status | launchd logs; runtime path; FAU home permissions |
| Keychain denials | Setup stalls | Re-run under real app bundle (not raw `swift run`) |
| Pair QR useless | Phone cannot connect | Host must be relay FQDN; tunnel up |
| Sleep regressions | Lid issues after FAU off | Confirm stay-awake reverted |

## 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

| Do | Don’t |
| - | - |
| Add UI that calls documented `/api` | Put IMAP or grant code in Swift |
| Keep logic in `FAUKit` with tests | Store secrets in UserDefaults |
| Preserve uninstall scripts | Point production launchd at a git checkout venv |

## 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.

## Related

* [Node](https://docs.fau.run/developer/protocol/node.md)
* [Mobile clients](https://docs.fau.run/developer/protocol/client-mobile.md)
* [Protocol overview](https://docs.fau.run/developer/protocol/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.