bot/docs/start/onboarding.md

summary, read_when, title, sidebarTitle

summary	read_when	title	sidebarTitle
First-run onboarding flow for Hanzo Bot (macOS app)	Designing the macOS onboarding assistant Implementing auth or identity setup	Onboarding (macOS App)	Onboarding: macOS App

Onboarding (macOS App)

This doc describes the current first‑run onboarding 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.

Where does the Gateway run?

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

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

Onboarding requests TCC permissions needed for:

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

This step is optional The app can install the global `bot` CLI via npm/pnpm so terminal workflows and launchd tasks work out of the box. 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](/start/bootstrapping) for what happens on the gateway host during the first agent run.