docs/setup/installation.md
The install script is the fastest way to get Agent Zero running. It handles Docker, image pulling, and container setup automatically.
macOS / Linux:
curl -fsSL https://bash.agent-zero.ai | bash
Windows (PowerShell):
irm https://ps.agent-zero.ai | iex
Docker (run directly):
docker run -p 80:80 agent0ai/agent-zero
Once the install completes, open the URL shown in your terminal to access the Web UI. Follow the prompts in the CLI to set your port and authentication, complete onboarding, add your API key, then continue to Step 3: Configure Agent Zero.
[!TIP] Prefer a terminal-native workflow too? Install the optional A0 CLI Connector from GitHub, then run
a0to connect to this Agent Zero instance from your terminal.
Use the built-in updater in the Web UI:
You'll also be prompted through the UI when a new A0 version is released. Backups are automatically managed internally during this process.
For technical details of the updater, see Self Update.
If you are upgrading from an older version of Agent Zero (v0.9.8 or earlier) to v1.1 or newer, the architecture has fundamentally changed. You cannot use the in-app Self Update. Instead, follow these steps to migrate your data:
usr/ directory (which contains your settings, projects, memory, and custom plugins).curl -fsSL https://bash.agent-zero.ai | bashirm https://ps.agent-zero.ai | iexusr/ directory into the new /a0/usr/ directory created by the script.Use this only if Self Update is unavailable or you must manage containers yourself (for example, some custom Docker setups).
docker pull agent0ai/agent-zero:latestdocker run -d -p 50081:80 --name agent-zero-new agent0ai/agent-zero[!CAUTION] Do not delete the old container until the new one has your data.
[!TIP] If the new instance fails to load settings, remove
/a0/usr/settings.jsonand restart to regenerate default settings.
Users should use Quick Start (Recommended) above. The steps below are for custom Docker setups, air-gapped installs, or when you cannot use the install scripts.
Follow the steps below to install Docker and run the image by hand.
Docker Desktop provides the runtime environment for Agent Zero, ensuring consistent behavior and security across platforms. The entire framework runs within a Docker container, providing isolation and easy deployment.
Choose your operating system:
<table> <tr> <td align="center" width="33%"> <a href="#windows-installation"><b>Windows</b> </a>
</td> <td align="center" width="33%"> <a href="#macos-installation"><b>macOS</b> </a>
</td> <td align="center" width="33%"> <a href="#linux-installation"><b>Linux</b> </a>
</td> </tr> </table><a name="windows-installation"></a>
1.1. Download Docker Desktop
Go to the Docker Desktop download page and download the Windows version (Intel/AMD is the main download button).
1.2. Run the Installer
Run the installer with default settings.
1.3. Launch Docker Desktop
Once installed, launch Docker Desktop from your Start menu or desktop shortcut.
✅ Docker is now installed!
Continue to Step 2: Run Agent Zero
<a name="macos-installation"></a>
1.1. Download Docker Desktop
Go to the Docker Desktop download page and download the macOS version (choose Apple Silicon or Intel based on your Mac).
1.2. Install Docker Desktop
Drag and drop the Docker application to your Applications folder.
1.3. Launch Docker Desktop
Open Docker Desktop from your Applications folder.
1.4. Configure Docker Socket
[!NOTE] Important macOS Configuration: In Docker Desktop's preferences (Docker menu) → Settings → Advanced, enable "Allow the default Docker socket to be used (requires password)."
✅ Docker is now installed!
Continue to Step 2: Run Agent Zero
<a name="linux-installation"></a>
1.1. Choose Installation Method
You can install either Docker Desktop or docker-ce (Community Edition).
Option A: Docker Desktop (Recommended for beginners)
Follow the instructions for your specific Linux distribution here.
Option B: docker-ce (Lightweight alternative)
Follow the installation instructions here.
1.2. Post-Installation Steps (docker-ce only)
If you installed docker-ce, add your user to the docker group:
sudo usermod -aG docker $USER
Log out and back in, then authenticate:
docker login
1.3. Launch Docker
If you installed Docker Desktop, launch it from your applications menu.
✅ Docker is now installed!
[!TIP] Deploying on a VPS/Server? For production deployments with reverse proxy, SSL, and domain configuration, see the VPS Deployment Guide.
Using Docker Desktop GUI:
agent0ai/agent-zero in Docker DesktopPull buttonUsing Terminal:
docker pull agent0ai/agent-zero
Choose or create a folder on your computer where Agent Zero will save its data.
Setting up persistence is needed only if you want your data and files to remain available even after you delete the container.
You can pick any location you find convenient:
C:\agent-zero-data/home/user/agent-zero-dataYou can map just the /a0/usr directory (recommended) or individual subfolders of /a0 to a local directory.
[!CAUTION] Do not map the entire
/a0directory: it contains the application code and can break upgrades.
[!TIP] Choose a location that's easy to access and backup. All your Agent Zero data will be directly accessible in this directory.
Using Docker Desktop GUI:
Run button next to the agent0ai/agent-zero image80 (set host port to 0 for automatic assignment)Run button
The container will start and show in the "Containers" tab:
The framework will take a few seconds to initialize. Find the mapped port in Docker Desktop (shown as <PORT>:80) or click the port right under the container ID:
Open http://localhost:<PORT> in your browser. The Web UI will open - Agent Zero is ready for configuration!
[!TIP] You can also access the Web UI by clicking the port link directly under the container ID in Docker Desktop.
[!NOTE] After starting the container, you'll find all Agent Zero files in your chosen directory. You can access and edit these files directly on your machine, and the changes will be immediately reflected in the running container.
Running A0 using Terminal?
docker run -p 0:80 -v /path/to/your/work_dir:/a0/usr agent0ai/agent-zero
0 with a fixed port if you prefer (e.g., 50080:80)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.
Agent Zero provides a comprehensive settings interface to customize various aspects of its functionality. Access the settings by clicking the "Settings" button with a gear icon in the sidebar.
agent0, hacker, researcher). Profiles can override prompts, tools, and extensions.See the Agent Profiles guide for profile file locations, agent.yaml, prompt overrides, and profile-specific Main/Utility model configuration.
[!NOTE] Since v0.9.7, custom prompts belong in
/a0/agents/<agent_name>/prompts/rather than a shared/promptsfolder. See the Extensions guide for details.
[!NOTE] The Hacker profile is included in the main image. After launch, choose the hacker agent profile in Settings to make it the default for new chats, or switch the selected chat from the composer profile selector. The "hacker" branch is deprecated.
Model naming is provider-specific.
Use claude-sonnet-4-5 for Anthropic, but use anthropic/claude-sonnet-4-5 for OpenRouter. If you see "Invalid model ID," verify the provider and naming format on the provider website, or search the web for "<name-of-ai-model> model naming".
[!TIP] Context window tuning: Set the total context window size first (for example, 100k), then adjust the chat history portion as a fraction of that total. A large fraction on a very large context window can still be enormous.
[!TIP] API URL: URL of the API endpoint for the chat model - only needed for some providers like Ollama, LM Studio, Azure, etc.
[!NOTE] Utility models need to be strong enough to extract and consolidate memory reliably. Very small models (e.g., 4B) often fail at this; 70B-class models or high-quality cloud "flash/mini" models work best.
[!NOTE] Agent Zero uses a local embedding model by default (runs on CPU), but you can switch to OpenAI embeddings like
text-embedding-3-smallortext-embedding-3-largeif preferred.
Configure API keys for various service providers directly within the Web UI. Click Save to confirm your settings.
[!NOTE] OpenAI API vs Plus subscription: A ChatGPT Plus subscription does not include API credits. You must provide a separate API key for OpenAI usage in Agent Zero.
[!TIP] For OpenAI-compatible providers (e.g., custom gateways or Z.AI/GLM), add the API key under External Services → Other OpenAI-compatible API keys, then select OpenAI Compatible as the provider in model settings.
[!CAUTION] GitHub Copilot Provider: When using the GitHub Copilot provider, after selecting the model and entering your first prompt, the OAuth login procedure will begin. You'll find the authentication code and link in the output logs. Complete the authentication process by following the provided link and entering the code, then you may continue using Agent Zero.
Learn more about Remote Function Calls in the Development Setup guide.
[!IMPORTANT] Always keep your API keys and passwords secure.
[!NOTE] On Windows host installs (non-Docker), you must use RFC to run shell code on the host system. The Docker runtime handles this automatically.
The Settings page is the control center for selecting the Large Language Models (LLMs) that power Agent Zero. You can choose different LLMs for different roles:
| LLM Role | Description |
|---|---|
chat_llm | This is the primary LLM used for conversations, agent reasoning, and tool use. Vision support controls image understanding. |
utility_llm | This LLM handles internal tasks like summarizing messages, managing memory, and processing internal prompts. Using a smaller, less expensive model here can improve efficiency. |
embedding_llm | The embedding model shipped with A0 runs on CPU and is responsible for generating embeddings used for memory retrieval and knowledge base lookups. Changing the embedding_llm will re-index all of A0's memory. |
How to Change:
[!NOTE] The built-in browser does not have a separate model slot. The main agent decides when to call the direct
browsertool.
Use the naming format required by your selected provider:
| Provider | Model Name Format | Example |
|---|---|---|
| OpenAI | Model name only | claude-sonnet-4-5 |
| OpenRouter | Provider prefix mostly required | anthropic/claude-sonnet-4-5 |
| Ollama | Model name only | gpt-oss:20b |
[!TIP] If you see "Invalid model ID," verify the provider and naming format on the provider website, or search the web for "<name-of-ai-model> model naming".
disable_thinking=true).Ollama is a powerful tool that allows you to run various large language models locally.
<a name="windows-ollama-installation"></a>
Download and install Ollama from the official website:
<button>Download Ollama Setup</button>
Once installed, continue to Pulling Models.
<a name="macos-ollama-installation"></a>
Using Homebrew:
brew install ollama
Using Installer:
Download from the official website.
Once installed, continue to Pulling Models.
<a name="linux-ollama-installation"></a>
Run the installation script:
curl -fsSL https://ollama.com/install.sh | sh
Once installed, continue to Pulling Models.
Finding Model Names:
Visit the Ollama model library for a list of available models and their corresponding names. Ollama models are referenced by model name only (for example, llama3.2).
Pull a model:
ollama pull <model-name>
Replace <model-name> with the name of the model you want to use. For example: ollama pull mistral-large
llama3.2 or qwen2.5:7bhttp://host.docker.internal:11434Save to confirm your settings.[!NOTE] If Agent Zero runs in Docker and Ollama runs on the host, ensure port 11434 is reachable from the container. If both services are in the same Docker network, you can use
http://<container_name>:11434instead ofhost.docker.internal.
Listing downloaded models:
ollama list
Removing a model:
ollama rm <model-name>
[!TIP] Experiment with different model combinations to find the balance of performance and cost that best suits your needs. E.g., faster and lower latency LLMs will help, and you can also use
faiss_gpuinstead offaiss_cpufor the memory.
Agent Zero can be accessed from mobile devices and other computers using the built-in Tunnel feature.
The Tunnel feature allows secure access to your Agent Zero instance from anywhere:
[!IMPORTANT] Security: Always set a username and password in Settings → Authentication before creating a tunnel to secure your instance on the internet.
For complete details on tunnel configuration and security considerations, see the Remote Access via Tunneling section in the Usage Guide.
If you prefer to keep access limited to your local network:
<PORT>:80, e.g., 32771:80)http://localhost:<PORT>http://<YOUR_COMPUTER_IP>:<PORT>[!TIP] Find your computer's IP address with
ipconfig(Windows) orifconfig/ip addr(macOS/Linux). It's usually in the format192.168.x.xor10.0.x.x.
For developers or users who need to run Agent Zero directly on their system, see the In-Depth Guide for Full Binaries Installation.
Agent Zero settings can be automatically configured using environment variables with the A0_SET_ prefix in your .env file. This enables automated deployments without manual configuration.
Usage:
Add variables to your .env file in the format:
A0_SET_{setting_name}={value}
Examples:
# Model configuration
A0_SET_chat_model_provider=anthropic
A0_SET_chat_model_name=claude-3-5-sonnet-20241022
A0_SET_chat_model_ctx_length=200000
# Memory settings
A0_SET_memory_recall_enabled=true
A0_SET_memory_recall_interval=5
# Agent configuration
A0_SET_agent_profile=custom
A0_SET_agent_memory_subdir=production
Docker usage:
When running Docker, you can pass these as environment variables:
docker run -p 50080:80 \
-e A0_SET_chat_model_provider=anthropic \
-e A0_SET_chat_model_name=claude-3-5-sonnet-20241022 \
agent0ai/agent-zero
Notes:
If you are migrating from older, non-Docker setups, A0 handles the migration of legacy folders and files automatically at runtime. The right place to save your files and directories is a0/usr.
After following the instructions for your specific operating system, you should have Agent Zero successfully installed and running. You can now start exploring the framework's capabilities and experimenting with creating your own intelligent agents.
Next Steps:
If you encounter any issues during the installation process, please consult the Troubleshooting section of this documentation or refer to the Agent Zero Skool or Discord community for assistance.