> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding (macOS App)

# Onboarding (macOS App)

This doc describes the **current** first‑run setup flow. The goal is a
smooth “day 0” experience: pick where the Gateway runs, connect auth, run the
wizard, and let the agent bootstrap itself.
For a general overview of onboarding paths, see [Onboarding Overview](https://agdiai-597e782f.mintlify.site/start/onboarding-overview.md).

**1. Approve macOS warning**

![](https://mintcdn.com/agdiai-597e782f/dgz7lCmhpS3UpOxQ/assets/macos-onboarding/01-macos-warning.jpeg?fit=max\&auto=format\&n=dgz7lCmhpS3UpOxQ\&q=85\&s=a4e0adb91b3e59be57287970ac900d31)

**2. Approve find local networks**

![](https://mintcdn.com/agdiai-597e782f/dgz7lCmhpS3UpOxQ/assets/macos-onboarding/02-local-networks.jpeg?fit=max\&auto=format\&n=dgz7lCmhpS3UpOxQ\&q=85\&s=ae9a89b994f57927e0b986825754c36f)

**3. Welcome and security notice**

![](https://mintcdn.com/agdiai-597e782f/dgz7lCmhpS3UpOxQ/assets/macos-onboarding/03-security-notice.png?fit=max\&auto=format\&n=dgz7lCmhpS3UpOxQ\&q=85\&s=0dc015cb98ccba1946d4c35f85ed9900)

Read the security notice displayed and decide accordingly

Security trust model:

* By default, Agdi is a personal agent: one trusted operator boundary.
* Shared/multi-user setups require lock-down (split trust boundaries, keep tool access minimal, and follow [Security](https://agdiai-597e782f.mintlify.site/gateway/security.md)).
* Local onboarding now defaults new configs to `tools.profile: "coding"` so fresh local setups keep filesystem/runtime tools without forcing the unrestricted `full` profile.
* If hooks/webhooks or other untrusted content feeds are enabled, use a strong modern model tier and keep strict tool policy/sandboxing.

**4. Local vs Remote**

![](https://mintcdn.com/agdiai-597e782f/dgz7lCmhpS3UpOxQ/assets/macos-onboarding/04-choose-gateway.png?fit=max\&auto=format\&n=dgz7lCmhpS3UpOxQ\&q=85\&s=565d9aaf2d52303f9d294c8cd2fc823f)

Where does the **Gateway** run?

* **This Mac (Local only):** onboarding can configure auth and write credentials
  locally.
* **Remote (over SSH/Tailnet):** onboarding does **not** configure local auth;
  credentials must exist on the gateway host.
* **Configure later:** skip setup and leave the app unconfigured.

> [!TIP]
>
> **Gateway auth tip:**
>
> * The wizard now generates a **token** even for loopback, so local WS clients must authenticate.
> * If you disable auth, any local process can connect; use that only on fully trusted machines.
> * Use a **token** for multi‑machine access or non‑loopback binds.

**5. Permissions**

![](https://mintcdn.com/agdiai-597e782f/dgz7lCmhpS3UpOxQ/assets/macos-onboarding/05-permissions.png?fit=max\&auto=format\&n=dgz7lCmhpS3UpOxQ\&q=85\&s=076ef66c84124bb09dc529c027ec1287)

Choose what permissions do you want to give Agdi

Onboarding requests TCC permissions needed for:

* Automation (AppleScript)
* Notifications
* Accessibility
* Screen Recording
* Microphone
* Speech Recognition
* Camera
* Location

**6. CLI**

\[!NOTE] This step is optional
The app can install the global `agdi` CLI via npm/pnpm so terminal
workflows and launchd tasks work out of the box.

**7. Onboarding Chat (dedicated session)**

After setup, the app opens a dedicated onboarding chat session so the agent can
introduce itself and guide next steps. This keeps first‑run guidance separate
from your normal conversation. See [Bootstrapping](https://agdiai-597e782f.mintlify.site/start/bootstrapping.md) for
what happens on the gateway host during the first agent run.


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