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

# Run a node

> Stand up a user mail node — local CLI, Mac app packaging, relay registration, and verification.

**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](https://docs.fau.run/developer/protocol/node.md). Spec: [Wire specification](https://docs.fau.run/developer/protocol/spec.md).

## Path A — End-user Mac (recommended)

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](https://docs.fau.run/developer/developers/build-macos.md)).
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.

```bash theme={null}
# from repo root — kernel + mail channel plugin
python3 -m venv .venv && source .venv/bin/activate
pip install -e node -e channels/mail
# optional: pip install -e "node[sqlcipher,dev]"
export FAU_HOME="$HOME/Library/Application Support/FAU-dev"   # or a temp dir
# Never put FAU_HOME under Documents/Desktop/Downloads (TCC).
python -m fedagent.cli --help
```

Register with a relay (after Gmail is configured in config / wizard equivalent):

```bash theme={null}
.venv/bin/python -m fedagent.cli relay register --url https://relay.fau.run
.venv/bin/python -m fedagent.cli relay status
```

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

```bash theme={null}
.venv/bin/python -m fedagent.cli status
.venv/bin/python -m fedagent.cli channels doctor
.venv/bin/python -m fedagent.cli channels smoke
curl -sS -H "X-FAU-Local: $(cat \"$FAU_HOME/local_token\")" \
  http://127.0.0.1:8765/api/status
curl -sS -H "X-FAU-Local: $(cat \"$FAU_HOME/local_token\")" \
  http://127.0.0.1:8765/api/channels
```

Optional Apple EventKit helper (Calendar/Reminders):

```bash theme={null}
./channels/apple_helper/install.sh
```

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

| Symptom | Check |
| - | - |
| Agents cannot TLS | Tunnel connected? Stay-awake? Relay healthy? |
| Sync errors | App password; IMAP host; FAU home permissions |
| Phone cannot pair | Pair QR `host` is relay FQDN, not `127.0.0.1` |

## Next

* Pair phone: [Build a mobile client](https://docs.fau.run/developer/developers/build-mobile.md) or reference `apps/phone`
* Dashboard routes: [Dashboard API](https://docs.fau.run/developer/protocol/dashboard.md)
* Extend tools/policy: [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.