Skip to content

Agent Zero AI framework

Document first-run onboarding flow

Alessandro818bda0385c3
diff --git a/docs/README.md b/docs/README.md
index 1b8615604..655dc0e44 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -12,6 +12,7 @@ docs focus on practical setup, screenshots, and user workflows.
## Quick Start
- **[Quickstart Guide](quickstart.md):** Get up and running in 5 minutes with Agent Zero.
+- **[First-Run Onboarding](guides/onboarding.md):** Choose Cloud or Local, add a provider key, and select main and utility models.
- **[Installation Guide](setup/installation.md):** Install scripts, updates, and advanced Docker setup (includes [How to Update](setup/installation.md#how-to-update-agent-zero)).
- **[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.
- **[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.
## User Guides
- **[Usage Guide](guides/usage.md):** Practical tour of Agent Zero's main workflows.
+- **[First-Run Onboarding](guides/onboarding.md):** Set up OpenRouter, our proxy API or another provider with the guided wizard.
- **[Browser Guide](guides/browser.md):** Use the built-in Browser, live Canvas surface, annotations, screenshots, host browser mode, and extensions.
- **[Desktop Guide](guides/desktop.md):** Use the built-in Linux desktop, GUI apps, and LibreOffice Writer/Calc/Impress Cowork.
- **[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.
- [Quick Start](#quick-start)
- [Quickstart Guide](quickstart.md)
+ - [First-Run Onboarding](guides/onboarding.md)
- [Installation Guide](setup/installation.md)
- [How to Update Agent Zero](setup/installation.md#how-to-update-agent-zero)
- [Manual Installation (Advanced)](setup/installation.md#manual-installation-advanced)
diff --git a/docs/guides/onboarding.md b/docs/guides/onboarding.md
new file mode 100644
index 000000000..012e56c5c
--- /dev/null
+++ b/docs/guides/onboarding.md
@@ -0,0 +1,74 @@
+# First-Run Onboarding
+
+Use onboarding the first time you open Agent Zero, or any time the Web UI says
+your models still need setup. The wizard helps you pick a provider, add the
+needed key or connection, choose the main model, choose the utility model, and
+start chatting.
+
+This example uses **Agent Zero API** with a fake demo key and
+`claude-opus-4-6`. Replace the demo key with your own key.
+
+## Choose Cloud Or Local
+
+Open the Web UI and click **Start Onboarding** from the welcome banner. On the
+first screen, choose whether Agent Zero should use a hosted provider or a local
+model server.
+
+![Onboarding start screen with Cloud and Local choices](../res/usage/onboarding/onboarding-start.png)
+
+Choose **Cloud** when you want to use Agent Zero API, OpenRouter, Anthropic,
+OpenAI, Google, Venice, or another hosted provider. Choose **Local** when you
+want to connect to Ollama, LM Studio, or another model server running on your
+machine.
+
+## Pick Agent Zero API
+
+On the Cloud provider screen, click **Agent Zero API**.
+
+![Cloud provider picker with Agent Zero API](../res/usage/onboarding/onboarding-cloud-provider.png)
+
+The ChatGPT/Codex account option is also available on this Cloud screen if you
+want to connect by device code instead of pasting a provider key.
+
+## Add The Key And Main Model
+
+Paste your Agent Zero API key in **API key**. The screenshot uses a fake example
+key, and the field is masked.
+
+Click the magnifier in **Main model** to open the model list, then choose
+`claude-opus-4-6`.
+
+![Agent Zero API setup with model dropdown open](../res/usage/onboarding/onboarding-agent-zero-api-model-dropdown.png)
+
+After the model is selected, click **Choose utility model**.
+
+![Agent Zero API setup with key and main model selected](../res/usage/onboarding/onboarding-agent-zero-api-key-model.png)
+
+## Choose The Utility Model
+
+The utility model handles supporting work such as summarizing, organizing
+memory, and other background tasks.
+
+Leave **Use same as Main Model** checked if you want both roles to use
+`claude-opus-4-6`.
+
+![Utility model step using the same model as main](../res/usage/onboarding/onboarding-utility-same-model.png)
+
+You can also uncheck **Use same as Main Model** and choose a different utility
+provider and model. For example, you might keep a strong main model for chat and
+use a faster or cheaper model for utility tasks.
+
+Click **Finish setup** when the utility model looks right.
+
+## Start Chatting
+
+The ready screen confirms that model setup is done. Optional setup cards may
+appear for integrations such as Telegram, Email, WhatsApp, or plugins.
+
+![Onboarding ready screen after setup](../res/usage/onboarding/onboarding-ready.png)
+
+Click **Start Chatting** to create a chat and begin using Agent Zero.
+
+> [!IMPORTANT]
+> Do not reuse the fake key shown in this guide. Paste your own provider key,
+> and do not share screenshots that reveal real keys or private account details.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index a9852fa05..59c569fe3 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -53,22 +53,21 @@ Once `a0` connects, open or create a chat there. The reasoning still belongs to
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).
-### Open the Web UI and configure your API key
+### Open the Web UI and complete onboarding
Open your browser and navigate to `http://localhost:<PORT>`. The Web UI will
-show the onboarding banner. Click **Start Onboarding** to set your models and
-API key.
+show the onboarding banner. Click **Start Onboarding** to choose Cloud or
+Local, add a provider key or account connection, and select your main and
+utility models.
![Agent Zero Web UI](res/setup/6-docker-a0-running-new.png)
-Click **Add your API key** to open Settings and configure:
-
-- **Default Provider:** OpenRouter (supports most models with a single API key)
-- **Alternative Providers:** Anthropic, OpenAI, Ollama/LM Studio (local models), and many others
-- **Model Selection:** Choose your chat model (e.g., `anthropic/claude-sonnet-4-6` for OpenRouter)
+For a screenshot walkthrough using **Agent Zero API** with
+`claude-opus-4-6`, see the [First-Run Onboarding guide](guides/onboarding.md).
> [!NOTE]
-> 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).
+> Agent Zero supports hosted providers and local models. You can use the same
+> provider for main and utility work, or choose separate providers for each.
### Start your first chat
diff --git a/docs/res/usage/onboarding/onboarding-agent-zero-api-key-model.png b/docs/res/usage/onboarding/onboarding-agent-zero-api-key-model.png
new file mode 100644
index 000000000..c46498169
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-agent-zero-api-key-model.png differ
diff --git a/docs/res/usage/onboarding/onboarding-agent-zero-api-model-dropdown.png b/docs/res/usage/onboarding/onboarding-agent-zero-api-model-dropdown.png
new file mode 100644
index 000000000..b899b35ad
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-agent-zero-api-model-dropdown.png differ
diff --git a/docs/res/usage/onboarding/onboarding-cloud-provider.png b/docs/res/usage/onboarding/onboarding-cloud-provider.png
new file mode 100644
index 000000000..efcb181fd
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-cloud-provider.png differ
diff --git a/docs/res/usage/onboarding/onboarding-ready.png b/docs/res/usage/onboarding/onboarding-ready.png
new file mode 100644
index 000000000..81b215f68
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-ready.png differ
diff --git a/docs/res/usage/onboarding/onboarding-start.png b/docs/res/usage/onboarding/onboarding-start.png
new file mode 100644
index 000000000..5102833d1
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-start.png differ
diff --git a/docs/res/usage/onboarding/onboarding-utility-same-model.png b/docs/res/usage/onboarding/onboarding-utility-same-model.png
new file mode 100644
index 000000000..992497535
Binary files /dev/null and b/docs/res/usage/onboarding/onboarding-utility-same-model.png differ
diff --git a/docs/setup/installation.md b/docs/setup/installation.md
index e97f0457e..9d153943a 100644
--- a/docs/setup/installation.md
+++ b/docs/setup/installation.md
@@ -300,7 +300,10 @@ docker run -p 0:80 -v /path/to/your/work_dir:/a0/usr agent0ai/agent-zero
## Step 3: Configure Agent Zero
-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.
+The UI will show a welcome banner when model setup is missing. Click
+**Start Onboarding** to choose Cloud or Local, add a provider key or account
+connection, and select your main and utility models. For the screenshot
+walkthrough, see the [First-Run Onboarding guide](../guides/onboarding.md).
### Settings Configuration