Document first-run onboarding flow
Add a screenshot-led guide for the guided onboarding wizard using Agent Zero API as the example setup. Link the guide from the docs hub, quickstart, and installation setup flow, and include optimized screenshots for choosing Cloud, selecting a provider, choosing models, and reaching the ready state.
Alessandro committed
May 9, 2026 at 08:05 UTC
818bda0385c392ae433913accaca277d5a2a50f4
10 files changed
+89
-10
docs/README.md
+3
@@ -12,6 +12,7 @@ docs focus on practical setup, screenshots, and user workflows.
12
## Quick Start
13
14
- **[Quickstart Guide](quickstart.md):** Get up and running in 5 minutes with Agent Zero.
15
+- **[First-Run Onboarding](guides/onboarding.md):** Choose Cloud or Local, add a provider key, and select main and utility models.
16
- **[Installation Guide](setup/installation.md):** Install scripts, updates, and advanced Docker setup (includes [How to Update](setup/installation.md#how-to-update-agent-zero)).
17
- **[A0 CLI Connector](guides/a0-cli-connector.md):** Install the host connector for a running Agent Zero instance, use the command palette, and switch Browser modes.
18
- **[Self Update](guides/self-update.md):** How the in-app updater works (technical reference).
@@ -21,6 +22,7 @@ docs focus on practical setup, screenshots, and user workflows.
22
## User Guides
23
24
- **[Usage Guide](guides/usage.md):** Practical tour of Agent Zero's main workflows.
25
+- **[First-Run Onboarding](guides/onboarding.md):** Set up OpenRouter, our proxy API or another provider with the guided wizard.
26
- **[Browser Guide](guides/browser.md):** Use the built-in Browser, live Canvas surface, annotations, screenshots, host browser mode, and extensions.
27
- **[Desktop Guide](guides/desktop.md):** Use the built-in Linux desktop, GUI apps, and LibreOffice Writer/Calc/Impress Cowork.
28
- **[A0 CLI Connector](guides/a0-cli-connector.md):** Terminal-first host connector for Agent Zero, with screenshots of the host picker, connected shell, command palette, and Browser modes.
@@ -61,6 +63,7 @@ docs focus on practical setup, screenshots, and user workflows.
63
64
- [Quick Start](#quick-start)
65
- [Quickstart Guide](quickstart.md)
66
+ - [First-Run Onboarding](guides/onboarding.md)
67
- [Installation Guide](setup/installation.md)
68
- [How to Update Agent Zero](setup/installation.md#how-to-update-agent-zero)
69
- [Manual Installation (Advanced)](setup/installation.md#manual-installation-advanced)
docs/guides/onboarding.md
new
+74
@@ -0,0 +1,74 @@
1
+# First-Run Onboarding
2
+
3
+Use onboarding the first time you open Agent Zero, or any time the Web UI says
4
+your models still need setup. The wizard helps you pick a provider, add the
5
+needed key or connection, choose the main model, choose the utility model, and
6
+start chatting.
7
+
8
+This example uses **Agent Zero API** with a fake demo key and
9
+`claude-opus-4-6`. Replace the demo key with your own key.
10
+
11
+## Choose Cloud Or Local
12
+
13
+Open the Web UI and click **Start Onboarding** from the welcome banner. On the
14
+first screen, choose whether Agent Zero should use a hosted provider or a local
15
+model server.
16
+
17
+
18
+
19
+Choose **Cloud** when you want to use Agent Zero API, OpenRouter, Anthropic,
20
+OpenAI, Google, Venice, or another hosted provider. Choose **Local** when you
21
+want to connect to Ollama, LM Studio, or another model server running on your
22
+machine.
23
+
24
+## Pick Agent Zero API
25
+
26
+On the Cloud provider screen, click **Agent Zero API**.
27
+
28
+
29
+
30
+The ChatGPT/Codex account option is also available on this Cloud screen if you
31
+want to connect by device code instead of pasting a provider key.
32
+
33
+## Add The Key And Main Model
34
+
35
+Paste your Agent Zero API key in **API key**. The screenshot uses a fake example
36
+key, and the field is masked.
37
+
38
+Click the magnifier in **Main model** to open the model list, then choose
39
+`claude-opus-4-6`.
40
+
41
+
42
+
43
+After the model is selected, click **Choose utility model**.
44
+
45
+
46
+
47
+## Choose The Utility Model
48
+
49
+The utility model handles supporting work such as summarizing, organizing
50
+memory, and other background tasks.
51
+
52
+Leave **Use same as Main Model** checked if you want both roles to use
53
+`claude-opus-4-6`.
54
+
55
+
56
+
57
+You can also uncheck **Use same as Main Model** and choose a different utility
58
+provider and model. For example, you might keep a strong main model for chat and
59
+use a faster or cheaper model for utility tasks.
60
+
61
+Click **Finish setup** when the utility model looks right.
62
+
63
+## Start Chatting
64
+
65
+The ready screen confirms that model setup is done. Optional setup cards may
66
+appear for integrations such as Telegram, Email, WhatsApp, or plugins.
67
+
68
+
69
+
70
+Click **Start Chatting** to create a chat and begin using Agent Zero.
71
+
72
+> [!IMPORTANT]
73
+> Do not reuse the fake key shown in this guide. Paste your own provider key,
74
+> and do not share screenshots that reveal real keys or private account details.
docs/quickstart.md
+8
-9
@@ -53,22 +53,21 @@ Once `a0` connects, open or create a chat there. The reasoning still belongs to
53
54
For the full setup flow, host picker screenshots, command palette guidance, Browser mode commands, manual fallback install paths, remote-host tips, and a copy-ready brief for another agent, see the [A0 CLI Connector guide](guides/a0-cli-connector.md).
55
56
-### Open the Web UI and configure your API key
56
+### Open the Web UI and complete onboarding
57
58
Open your browser and navigate to `http://localhost:<PORT>`. The Web UI will
59
-show the onboarding banner. Click **Start Onboarding** to set your models and
60
-API key.
59
+show the onboarding banner. Click **Start Onboarding** to choose Cloud or
60
+Local, add a provider key or account connection, and select your main and
61
+utility models.
62
63
64
64
-Click **Add your API key** to open Settings and configure:
65
-
66
-- **Default Provider:** OpenRouter (supports most models with a single API key)
67
-- **Alternative Providers:** Anthropic, OpenAI, Ollama/LM Studio (local models), and many others
68
-- **Model Selection:** Choose your chat model (e.g., `anthropic/claude-sonnet-4-6` for OpenRouter)
65
+For a screenshot walkthrough using **Agent Zero API** with
66
+`claude-opus-4-6`, see the [First-Run Onboarding guide](guides/onboarding.md).
67
68
> [!NOTE]
71
-> Agent Zero supports any LLM provider, including local models via Ollama. For detailed provider configuration and local model setup, see the [Installation Guide](setup/installation.md#choosing-your-llms).
69
+> Agent Zero supports hosted providers and local models. You can use the same
70
+> provider for main and utility work, or choose separate providers for each.
71
72
### Start your first chat
73
docs/res/usage/onboarding/onboarding-agent-zero-api-key-model.png
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-agent-zero-api-key-model.png differ
docs/res/usage/onboarding/onboarding-agent-zero-api-model-dropdown.png
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-agent-zero-api-model-dropdown.png differ
docs/res/usage/onboarding/onboarding-cloud-provider.png
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-cloud-provider.png differ
docs/res/usage/onboarding/onboarding-ready.png
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-ready.png differ
docs/res/usage/onboarding/onboarding-start.png
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-start.png differ
docs/res/usage/onboarding/onboarding-utility-same-model.png
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-utility-same-model.png differ
docs/setup/installation.md
+4
-1
@@ -300,7 +300,10 @@ docker run -p 0:80 -v /path/to/your/work_dir:/a0/usr agent0ai/agent-zero
300
301
## Step 3: Configure Agent Zero
302
303
-The UI will show a warning banner "Missing LLM API Key for current settings". Click on `Add your API key` to enter Settings and start configuring A0.
303
+The UI will show a welcome banner when model setup is missing. Click
304
+**Start Onboarding** to choose Cloud or Local, add a provider key or account
305
+connection, and select your main and utility models. For the screenshot
306
+walkthrough, see the [First-Run Onboarding guide](../guides/onboarding.md).
307
308
### Settings Configuration
309