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

# Build the macOS client

> Build, run, and package the menu bar app that supervises the node.

**Purpose:** produce a working **macOS supervisor** (menu bar + NodeRuntime + launchd).

**Audience:** developers changing `apps/macos/` or cutting DMGs.

## What this client is

A thin Swift shell. It does **not** sync mail or evaluate grants. It installs the
bundled node, seals keys, shows pair QR, and talks to loopback `/api/*`.

Architecture: [macOS client](https://docs.fau.run/developer/protocol/client-macos.md). Dashboard contract:
[Dashboard API](https://docs.fau.run/developer/protocol/dashboard.md).

## Prerequisites

* macOS 14+
* Swift 5.9+ (Xcode 15+ recommended for full toolchain)
* For distribution: Apple Developer ID + notary profile

## 1. Build the app bundle

```bash theme={null}
cd apps/macos
bash scripts/build-app.sh
open dist/FAUMenuBar.app
```

`NodeRuntime` (CPython + `fedagent`) is bundled by default. Set `SKIP_NODE_RUNTIME=1`
only for Swift-only iteration.

## 2. Run tests

```bash theme={null}
cd apps/macos
bash scripts/verify-without-xcode.sh
# or: swift test
```

## 3. Make a local DMG

```bash theme={null}
cd apps/macos
bash scripts/build-dmg.sh --skip-sign --download
```

Ad-hoc signed → **this Mac only**. Gatekeeper: right-click → Open.

Notarized builds: set `FAU_TEAM_ID` / `FAU_SIGN_IDENTITY` and run without `--skip-sign`.

## 4. Verify

1. App launches; menu bar item appears.
2. Wizard can reach loopback status API.
3. After Gmail + relay: pair QR uses relay hostname (not `127.0.0.1`).
4. FAU off restores sleep (stay-awake reverted).

## Invariants

* Never put `FAU_HOME` / runtime under Documents, Desktop, or Downloads
* Never call `/papi` or `/mcp` from the Mac app as a device/agent
* Uninstall scripts must remain safe (`scripts/uninstall.sh`)

## Next

* [Run a node](https://docs.fau.run/developer/developers/run-node.md) — operational checklist
* [Build a mobile client](https://docs.fau.run/developer/developers/build-mobile.md) — pair against this install
* [Extend the codebase](https://docs.fau.run/developer/developers/extend.md)


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