Documentation

Installation

Install Agent Zero with one script, open the Web UI, and configure your models in a few steps.

  • Run one command for macOS, Linux, or Windows
  • Answer the first-run prompts
  • Open the local Web UI
  • Connect your preferred model provider
Agent Zero installation walkthrough Play video

Install Agent Zero

This page contains the full onboarding path in the recommended order: install, first run, open the Web UI, add host control if you need it, configure models, then move into the ongoing topics like local models, persistence, updates, and sharing.

Step 0

Run the install script for your platform

Open your terminal or PowerShell, run the command below, and keep that window open while the installer finishes. The script handles Docker detection, image startup, and the handoff into the first-run flow.

# Recommended: installs and launches Agent Zero for macOS or Linux.
$ curl -fsSL https://bash.agent-zero.ai | bash
# Recommended: run this in PowerShell.
> irm https://ps.agent-zero.ai | iex
# Advanced fallback: manual container start when you are not using the installer.
$ docker run -p 80:80 agent0ai/agent-zero
  • Best default for most users
  • Handles Docker setup and startup
  • Moves directly into first-run onboarding
Step 1

Answer the first-run prompts

The installer is designed to get you to a running instance quickly. Depending on your platform and existing Docker setup, it may ask you to confirm or choose:

  • Docker installation or permission steps if Docker is not ready yet
  • The local port Agent Zero should use
  • Authentication credentials for the Web UI and remote access

You can revisit authentication settings later from Settings > External Services > Authentication.

Step 2

Open the Web UI

When installation completes, the CLI prints the local address for your instance. Open that address in your browser, usually http://localhost:<PORT>, and continue the onboarding flow there.

Add host control with A0 CLI

Agent Zero runs in Docker by default. If you want it to work on files on your own computer, run commands in your host terminal, or use your host browser profile, install A0 CLI on the host machine before you configure models.

Optional

Install A0 CLI on this computer

Run the command for your platform in your host terminal or PowerShell, not inside the Agent Zero container. After it connects, Agent Zero can request access to local files, terminal execution, and Bring Your Own Browser workflows.

# Installs A0 CLI on your host computer.
$ curl -LsSf https://cli.agent-zero.ai/install.sh | sh
# Installs A0 CLI from Windows PowerShell.
> irm https://cli.agent-zero.ai/install.ps1 | iex

For the full setup path, open the A0 CLI Connector guide.

Configure models and providers

Once the Web UI opens, finish onboarding by connecting at least one model provider. Use the guided onboarding prompt if it appears, or open the same flow again from Settings later. The goal is simple: choose Cloud or Local, add a key or account connection if required, then pick your main and utility models.

Agent Zero onboarding screen with Cloud and Local choices
Step 3

Complete the onboarding wizard

  1. Choose Cloud for OpenRouter, our proxy API, Anthropic, OpenAI, Google, Venice, or another hosted provider.
  2. Choose Local for Ollama, LM Studio, or another model server running on your machine.
  3. Pick the provider, paste the API key if that provider requires one, then choose the main model.
  4. Keep the utility model the same as the main model, or choose a separate utility provider and model.
  5. Click Finish setup, then start chatting.

Good default: use the same provider for main and utility work on day one, confirm the agent can chat successfully, then optimize individual model choices later.

Onboarding model dropdown with model choices

For the full screenshot walkthrough, open the First-Run Onboarding guide.

Run local models

Cloud providers are the fastest way to get started. If you want privacy-first or offline operation, run a local model server on the host machine and point Agent Zero at it from the same model configuration flow you used above.

Ollama

Great default for local inference. It is simple to install and works well for most self-hosted setups.

LM Studio

Good if you prefer a desktop app workflow and want to use its OpenAI-compatible local server.

Ollama quick path

  • Windows/macOS: install Ollama from ollama.com
  • Linux: run curl -fsSL https://ollama.com/install.sh | sh
# Start with a practical general model
ollama pull llama3.2

# Optional smaller variant
ollama pull llama3.2:1b
  1. Open the model configuration screen in Agent Zero.
  2. Select Ollama as the provider for the model slot you want to change.
  3. Use http://host.docker.internal:11434 as the base URL.
  4. Enter the local model name, then save.

Note: if your Docker setup does not expose host.docker.internal, use the host machine IP address instead.

For LM Studio, enable its local API server and use the base URL shown there from inside the same model configuration flow.

Local model configuration in Agent Zero

Understand the model roles

Chat model

The main reasoning model used for conversation, planning, and most higher-value work.

Utility model

Helper model for faster supporting tasks. You can keep it on the same provider at first.

Embedding model

Powers memory and knowledge indexing. Changing it later can trigger reindexing work.

Data persistence and backups

Your running container can be replaced or recreated over time, so think about data before you upgrade or experiment. The safest default is still the built-in backup flow.

Option 1: Backup and Restore

  1. Open Settings -> Backup & Restore.
  2. Create a backup and keep the file somewhere safe.
  3. Restore that backup into a fresh installation or container when needed.

Option 2: Volume mapping

Use a Docker volume or bind mount only when you want a host-managed directory. Map a folder on your machine to /a0/usr inside the container. 

docker run -d -p 50080:80 -v /path/to/local/folder:/a0/usr --name agent-zero agent0ai/agent-zero
  • Do not map the entire /a0 directory when upgrading.
  • Prefer one clean mapping to /a0/usr.
  • Create a backup before major updates even if you already use volumes.

Network access and sharing

You can keep Agent Zero local, expose it to devices on your network, or share it over the internet once authentication is enabled.

Local network

  1. Find your computer IP address with ipconfig on Windows or ifconfig / ip addr on macOS and Linux.
  2. From another device on the same network, open http://your-ip:your-port.
  3. Example: http://192.168.1.100:50080.

Internet access

  1. Enable authentication first.
  2. Open the tunnel or sharing section in Settings.
  3. Create a tunnel and use the generated URL or QR code.

For more detail, the separate Sharing guide expands on network access and safe collaboration.

Security reminder: never expose the instance to the internet without Web UI authentication enabled.

Need help?

If the install script or onboarding flow does not behave as expected, the community channels below are the fastest place to compare notes and get unstuck.

Community support

Useful next docs