Documentation

First-Run Onboarding

Use onboarding the first time you start Agent Zero. The wizard helps you choose a provider, add API keys or a local model setup, and pick the main and utility models.

Choose Cloud Or Local

Open the Web UI and click Start Onboarding from the welcome banner.

Use this path when you want a hosted provider. Pick the provider, paste your key or connect your account, choose a main model, then choose a utility model. Cloud models are usually the easiest way to start.

Use this path when Ollama is running locally. Install Ollama, pull the model, then choose Ollama in onboarding and enter the exact model name. 

ollama pull gemma4:26b
ollama run gemma4:26b
  • Ollama serves models on localhost:11434 by default.
  • If Agent Zero runs in Docker and Ollama runs on the host, use http://host.docker.internal:11434 when an API URL field is shown.
  • Use the exact Ollama model name, for example gemma4:26b.
  • Local requests stay on your machine, but a local model may be slower or less capable depending on the model and your hardware.
Onboarding start screen with Cloud and Local choices

Pick A Provider

On the Cloud provider screen, select the provider you want to use. 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.

Cloud provider picker with Agent Zero API visible

Add The Key And Main Model

Paste your provider key in API key. The screenshots use a fake example key and the field is masked. Click the magnifier in Main model to open the model list, then choose the model you want.

Provider setup with model dropdown open

After the model is selected, click Choose utility model.

Provider setup with key and main model selected

Configure Local Ollama

Choose Ollama as the provider, enter gemma4:26b as the model name, and continue through the same main-model and utility-model steps. Ollama usually does not need a real API key; if the field is required in your build, use a harmless placeholder such as ollama.

Ollama provider selected with gemma4:26b model name

Best to know: start Ollama before onboarding. If Agent Zero cannot connect, confirm the model responds locally with ollama run gemma4:26b, then check whether Docker should reach it at http://host.docker.internal:11434.

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 the same model.

Utility model step using the same model as main

You can also uncheck Use same as Main Model and choose a different utility provider and model. For example, keep a stronger main model for chat and use a faster or cheaper model for utility tasks.

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. Click Start Chatting to create a chat.

Onboarding ready screen after setup

Important: do not reuse fake keys shown in screenshots. Paste your own provider key, and do not share screenshots that reveal real keys or private account details.