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
Install Agent Zero
This page contains the full onboarding path in the recommended order: install, first run, open the Web UI, configure models, then move into the ongoing topics like local models, persistence, updates, and sharing.
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.
- Best default for most users
- Handles Docker setup and startup
- Moves directly into first-run onboarding
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
- Whether to launch immediately into the onboarding flow
Keep note of the chosen port. You will use it in the next step, and you can revisit authentication later from Settings -> Authentication.
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.
If the script chose the port
Use the exact localhost URL printed in the terminal output.
If you set a custom port
Open http://localhost:your-port in the browser on the same machine.
If Docker assigned a random port
Use the printed mapping or the port shown in Docker Desktop.
Manual Docker workflow
Use this only when you need custom Docker flags, you are troubleshooting a script issue, or you intentionally want to manage the container yourself.
docker pull agent0ai/agent-zero:latest
# Basic run
docker run -d -p 50080:80 --name agent-zero agent0ai/agent-zero
# Persist user data
docker run -d -p 50080:80 -v /path/to/local/data:/a0/usr --name agent-zero agent0ai/agent-zero- Use a host port such as
50080if80is already in use. - Map only
/a0/usrwhen you need persistent user data. - Jump to Data Persistence & Backups before managing volumes manually.
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 reopen the model configuration flow from Settings. The goal is simple: give Agent Zero a provider, an API key if required, and a first set of models.
Connect a provider and pick your first models
- Open the onboarding prompt or the model configuration screen in Settings.
- Choose the provider you want to start with.
- Paste the API key if that provider requires one.
- Select a chat model first, then set utility, browser, and embedding models.
- Save the configuration and return to chat.
Good default: use the same provider for every model slot on day one, confirm the agent can chat successfully, then optimize individual model choices later.
Provider examples
Provider setup should be understood once, not repeated for every vendor. Agent Zero supports multiple providers; these are simply common places to get your first API key.
OpenRouter
Useful if you want one API surface for many model families and easy experimentation across providers.
OpenAI
Useful if you want direct access to OpenAI models and prefer a single-provider setup.
Anthropic
Useful if you want direct access to Claude models and Anthropic-native usage.
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.
Secure the UI before sharing it
If you plan to access Agent Zero from another device or expose it to the internet, enable authentication before you share the instance.
- UI login: set the username and password used to access the Web UI.
- Root or shell password: set this only if you plan to use remote shell access.
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- Open the model configuration screen in Agent Zero.
- Select Ollama as the provider for the model slot you want to change.
- Use
http://host.docker.internal:11434as the base URL. - 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.
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
- Open Settings -> Backup & Restore.
- Create a backup and keep the file somewhere safe.
- 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
/a0directory when upgrading. - Prefer one clean mapping to
/a0/usr. - Create a backup before major updates even if you already use volumes.
What is stored there
/agentsfor agent configurations/usr/projectsfor projects and files/memoryfor chat history and memories/knowledgefor knowledge files/promptsfor custom prompt templates/tmp/settings.jsonand related user settings.envand similar configuration values
Updating Agent Zero
If you are here specifically for upgrades, use the dedicated Updating guide. The short version is below for convenience.
Self Update
- Open Settings UI -> Update.
- Open Self Update.
- Apply the update after reviewing the version available.
Older installations
If you are upgrading from v0.9.8 or earlier, rerun the modern install script and migrate your backed-up user data into the new installation layout.
Manual update fallback
- Pull the latest image.
- Start a new container on a different port.
- Back up from the old instance and restore into the new one.
- Delete the old container only after the new one is verified.
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
- Find your computer IP address with
ipconfigon Windows orifconfig/ip addron macOS and Linux. - From another device on the same network, open
http://your-ip:your-port. - Example:
http://192.168.1.100:50080.
Internet access
- Enable authentication first.
- Open the tunnel or sharing section in Settings.
- 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.