| 1 | # Installation Guide |
| 2 | |
| 3 | ## **Goal:** Go from zero to a first working chat with minimal setup. |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## Quick Start (Recommended) |
| 8 | |
| 9 | Agent Zero runs as a Docker container, and you now have two friendly ways to get |
| 10 | there: |
| 11 | |
| 12 | - **A0 Launcher** is the desktop app. It can download Agent Zero, create and |
| 13 | manage Instances, and help set up the local container runtime when needed. |
| 14 | - **A0 Install** is the terminal installer. It is best for SSH sessions, |
| 15 | servers, scripted setup, recovery shells, or users who prefer commands. |
| 16 | |
| 17 | If Docker is already installed and running, you can also start the container |
| 18 | directly. |
| 19 | |
| 20 | ### A0 Launcher |
| 21 | |
| 22 | Use **A0 Launcher** when you want the guided desktop path. Download the app for |
| 23 | your platform, open it, and let it check Docker or set up a runtime before it |
| 24 | downloads Agent Zero. |
| 25 | |
| 26 | #### Downloads |
| 27 | |
| 28 | | Architecture | macOS | Linux | Windows | |
| 29 | | --- | --- | --- | --- | |
| 30 | | x86 | [Mac Intel](https://github.com/agent0ai/a0-launcher/releases/download/v0.9/a0-launcher-0.9-macos-x64.dmg) | [Linux x86](https://github.com/agent0ai/a0-launcher/releases/download/v0.9/a0-launcher-0.9-linux-x64.AppImage) | [Windows x86](https://github.com/agent0ai/a0-launcher/releases/download/v0.9/a0-launcher-0.9-windows-x64.exe) | |
| 31 | | ARM64 | [Mac Apple Silicon](https://github.com/agent0ai/a0-launcher/releases/download/v0.9/a0-launcher-0.9-macos-arm64.dmg) | [Linux ARM64](https://github.com/agent0ai/a0-launcher/releases/download/v0.9/a0-launcher-0.9-linux-arm64.AppImage) | [Windows ARM64](https://github.com/agent0ai/a0-launcher/releases/download/v0.9/a0-launcher-0.9-windows-arm64.exe) | |
| 32 | |
| 33 | See the [A0 Launcher v0.9 release](https://github.com/agent0ai/a0-launcher/releases/tag/v0.9) |
| 34 | for release notes and updater metadata. See the |
| 35 | [Launcher guide](../guides/launcher.md) for the first-run walkthrough. |
| 36 | |
| 37 | ### A0 Install |
| 38 | |
| 39 | Use **A0 Install** when you want the command-line path. The installer creates a |
| 40 | Dockerized Agent Zero instance, mounts user data to `/a0/usr`, and tries to |
| 41 | reuse an existing Docker-compatible runtime before setting one up. |
| 42 | |
| 43 | #### macOS / Linux |
| 44 | ```bash |
| 45 | curl -fsSL https://bash.agent-zero.ai | bash |
| 46 | ``` |
| 47 | |
| 48 | #### Windows PowerShell |
| 49 | ```powershell |
| 50 | irm https://ps.agent-zero.ai | iex |
| 51 | ``` |
| 52 | |
| 53 | #### Headless / scripted |
| 54 | |
| 55 | For servers and automation, Quick Start mode creates one instance and exits |
| 56 | without opening menus: |
| 57 | |
| 58 | ```bash |
| 59 | curl -fsSL https://bash.agent-zero.ai | bash -s -- --quick-start --name agent-zero --port 5080 |
| 60 | ``` |
| 61 | |
| 62 | ```powershell |
| 63 | & ([scriptblock]::Create((irm https://ps.agent-zero.ai))) -QuickStart -Name agent-zero -Port 5080 |
| 64 | ``` |
| 65 | |
| 66 | Use `--skip-runtime-setup` / `-SkipRuntimeSetup` when Docker must already be |
| 67 | working and the installer should not try to set up a runtime. See the |
| 68 | [A0 Install repository](https://github.com/agent0ai/a0-install) for all |
| 69 | installer flags. |
| 70 | |
| 71 | ### Docker already installed? Run this directly |
| 72 | |
| 73 | ```bash |
| 74 | docker run -p 80:80 -v a0_usr:/a0/usr agent0ai/agent-zero |
| 75 | ``` |
| 76 | |
| 77 | Once the install completes, open the URL shown in your terminal or Launcher to |
| 78 | access the Web UI. Complete onboarding, add your model provider or API key, then |
| 79 | continue to [Step 3: Configure Agent Zero](#step-3-configure-agent-zero). |
| 80 | |
| 81 | > [!TIP] |
| 82 | > Need Agent Zero to reach host-machine files, shell, or a host browser? Install the optional [A0 CLI Connector](../guides/a0-cli-connector.md), then run `a0` to connect your terminal to this Agent Zero instance. |
| 83 | |
| 84 | --- |
| 85 | |
| 86 | ## How to Update Agent Zero |
| 87 | |
| 88 | ### Self Update (Recommended) |
| 89 | |
| 90 | Use the built-in updater in the Web UI: |
| 91 | |
| 92 | 1. Open **Settings UI -> Update** tab |
| 93 | 2. Open **Self Update** |
| 94 | 3. Wait for the update checker to see if you have the latest version or if there's an available update. |
| 95 | |
| 96 | You'll also be prompted through the UI when a new A0 version is released. Backups are automatically managed internally during this process. |
| 97 | |
| 98 | For technical details of the updater, see [Self Update](../guides/self-update.md). |
| 99 | |
| 100 | ### Updating from v1.20 to v2.0 |
| 101 | |
| 102 | Agent Zero v2.0 starts a new major release line. If your instance is on v1.20, |
| 103 | the in-app Self Update can show the newer v2.x line, but it will not apply that |
| 104 | jump inside the existing v1 Docker image. The safe path is: |
| 105 | |
| 106 | 1. Create a backup zip from the old v1.20 instance. |
| 107 | 2. Pull the new `agent0ai/agent-zero:latest` Docker image. For the v2.0 release, |
| 108 | `latest` is the v2.0 image. |
| 109 | 3. Start a new container from that image. |
| 110 | 4. Restore the backup zip into the new v2.0 instance. |
| 111 | |
| 112 |  |
| 113 | |
| 114 | #### Without Agent Zero Launcher |
| 115 | |
| 116 | Use this path if you manage Agent Zero directly from Docker Desktop or Docker |
| 117 | CLI. |
| 118 | |
| 119 | 1. Open your old v1.20 Web UI and create a backup from **Settings -> Check for Updates -> Backup & Restore -> Create Backup**. Keep the downloaded `.zip` file. |
| 120 | 2. Pull the v2.0 image. In **Docker Desktop**, search for `agent0ai/agent-zero:latest` and pull that image. In **Docker CLI**, run: |
| 121 | ```bash |
| 122 | docker pull agent0ai/agent-zero:latest |
| 123 | ``` |
| 124 | 3. Start a new v2.0 container on a different host port so the old instance stays available: |
| 125 | ```bash |
| 126 | docker run -d -p 50081:80 --name agent-zero-v2 -v a0_v2_usr:/a0/usr agent0ai/agent-zero:latest |
| 127 | ``` |
| 128 | 4. Open the new v2.0 instance, complete any first-run prompts, then restore the downloaded `.zip` from **Settings -> Check for Updates -> Backup & Restore -> Restore Backup**. |
| 129 | 5. Verify chats, projects, memory, settings, and custom plugins before removing the old v1.20 container. |
| 130 | |
| 131 | #### With Agent Zero Launcher |
| 132 | |
| 133 | Launcher gives you the same backup/restore idea from the **Instances** page. |
| 134 | |
| 135 | 1. Open **Instances**, choose the old v1.20 Instance, and use **Backup `/a0/usr`**. |
| 136 | 2. Open **Installs**, use the **latest** card, then **Install** or **Run** the image. For the v2.0 release, **latest** is the v2.0 image. |
| 137 | 3. Return to **Instances**, choose the new v2.0 Instance, and use **Restore `/a0/usr`** with the backup zip. |
| 138 | 4. Open the new Instance and verify it before deleting or stopping the old v1.20 container. |
| 139 | |
| 140 | Launcher keeps old and new Instances visible separately, which makes it easier |
| 141 | to compare them before cleanup. |
| 142 | |
| 143 | > [!CAUTION] |
| 144 | > Do not try to solve the v1.20 -> v2.0 jump by bind-mounting the whole old |
| 145 | > `/a0` directory into a new container. Keep user data under `/a0/usr`, use the |
| 146 | > backup/restore flow, and let the new image provide the v2.0 system files. |
| 147 | |
| 148 | ### Updating from Pre-v0.9.8 |
| 149 | |
| 150 | If you are upgrading from Agent Zero v0.9.8 or earlier to v1.1 or newer, use the migration path below. Older installs were laid out differently, so the in-app Self Update is not the right tool for that jump. |
| 151 | |
| 152 | 1. **Backup your existing `usr/` directory** (which contains your settings, projects, memory, and custom plugins). |
| 153 | 2. **Run the new install script** to set up the current Docker-based install: |
| 154 | - macOS / Linux: `curl -fsSL https://bash.agent-zero.ai | bash` |
| 155 | - Windows (PowerShell): `irm https://ps.agent-zero.ai | iex` |
| 156 | 3. **Migrate your data:** After the new installation completes, copy the contents of your backed-up `usr/` directory into the new `/a0/usr/` directory created by the script. |
| 157 | 4. Restart the container for the changes to take effect. |
| 158 | |
| 159 | ### Manual Update (Advanced) |
| 160 | |
| 161 | > Use this only if Self Update is unavailable or you must manage containers yourself (for example, some custom Docker setups). |
| 162 | |
| 163 | 1. Keep the current container running |
| 164 | 2. `docker pull agent0ai/agent-zero:latest` |
| 165 | 3. Start a **new** container on a different host port, for example: `docker run -d -p 50081:80 --name agent-zero-new agent0ai/agent-zero:latest` |
| 166 | 4. On the **old** instance: **Settings -> Check for Updates -> Backup & Restore -> Create Backup** |
| 167 | 5. On the **new** instance: restore the downloaded backup zip |
| 168 | 6. Verify chats and data, then remove the old container |
| 169 | |
| 170 | > [!CAUTION] |
| 171 | > Do not delete the old container until the new one has your data. |
| 172 | |
| 173 | > [!TIP] |
| 174 | > If the new instance fails to load settings, remove `/a0/usr/settings.json` and restart to regenerate default settings. |
| 175 | |
| 176 | --- |
| 177 | |
| 178 | ## Manual Installation (Advanced) |
| 179 | |
| 180 | > Users should use [Quick Start (Recommended)](#quick-start-recommended) above. The steps below are for custom Docker setups, air-gapped installs, or when you cannot use the install scripts. |
| 181 | |
| 182 | Follow the steps below to install Docker and run the image by hand. |
| 183 | |
| 184 | ### Step 1: Install Docker Desktop |
| 185 | |
| 186 | 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. |
| 187 | |
| 188 | **Choose your operating system:** |
| 189 | |
| 190 | <table> |
| 191 | <tr> |
| 192 | <td align="center" width="33%"> |
| 193 | <a href="#windows-installation"> |
| 194 | <img src="../res/setup/oses/windows.png" width="80" alt="Windows"/><br/> |
| 195 | <b>Windows</b> |
| 196 | </a> |
| 197 | </td> |
| 198 | <td align="center" width="33%"> |
| 199 | <a href="#macos-installation"> |
| 200 | <img src="../res/setup/oses/apple.png" width="80" alt="macOS"/><br/> |
| 201 | <b>macOS</b> |
| 202 | </a> |
| 203 | </td> |
| 204 | <td align="center" width="33%"> |
| 205 | <a href="#linux-installation"> |
| 206 | <img src="../res/setup/oses/linux.png" width="80" alt="Linux"/><br/> |
| 207 | <b>Linux</b> |
| 208 | </a> |
| 209 | </td> |
| 210 | </tr> |
| 211 | </table> |
| 212 | |
| 213 | --- |
| 214 | |
| 215 | <a name="windows-installation"></a> |
| 216 | #### <img src="../res/setup/oses/windows.png" width="30" alt="Windows"/> Windows Installation |
| 217 | |
| 218 | **1.1. Download Docker Desktop** |
| 219 | |
| 220 | Go to the [Docker Desktop download page](https://www.docker.com/products/docker-desktop/) and download the Windows version (Intel/AMD is the main download button). |
| 221 | |
| 222 | <img src="../res/setup/image-8.png" alt="docker download" width="200"/> |
| 223 | <br><br> |
| 224 | |
| 225 | **1.2. Run the Installer** |
| 226 | |
| 227 | Run the installer with default settings. |
| 228 | |
| 229 | <img src="../res/setup/image-9.png" alt="docker install" width="300"/> |
| 230 | <img src="../res/setup/image-10.png" alt="docker install" width="300"/> |
| 231 | <br><br> |
| 232 | |
| 233 | **1.3. Launch Docker Desktop** |
| 234 | |
| 235 | Once installed, launch Docker Desktop from your Start menu or desktop shortcut. |
| 236 | |
| 237 | <img src="../res/setup/image-11.png" alt="docker installed" height="100"/> |
| 238 | |
| 239 | **Docker is now installed.** |
| 240 | |
| 241 | Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero) |
| 242 | |
| 243 | --- |
| 244 | |
| 245 | <a name="macos-installation"></a> |
| 246 | #### <img src="../res/setup/oses/apple.png" width="30" alt="macOS"/> macOS Installation |
| 247 | |
| 248 | **1.1. Download Docker Desktop** |
| 249 | |
| 250 | Go to the [Docker Desktop download page](https://www.docker.com/products/docker-desktop/) and download the macOS version (choose Apple Silicon or Intel based on your Mac). |
| 251 | |
| 252 | <img src="../res/setup/image-8.png" alt="docker download" width="200"/> |
| 253 | <br><br> |
| 254 | |
| 255 | **1.2. Install Docker Desktop** |
| 256 | |
| 257 | Drag and drop the Docker application to your Applications folder. |
| 258 | |
| 259 | <img src="../res/setup/image-12.png" alt="docker install" width="300"/> |
| 260 | <br><br> |
| 261 | |
| 262 | **1.3. Launch Docker Desktop** |
| 263 | |
| 264 | Open Docker Desktop from your Applications folder. |
| 265 | |
| 266 | <img src="../res/setup/image-13.png" alt="docker installed" height="100"/> |
| 267 | <br><br> |
| 268 | |
| 269 | **1.4. Configure Docker Socket** |
| 270 | |
| 271 | > [!NOTE] |
| 272 | > **Important macOS Configuration:** In Docker Desktop's preferences (Docker menu) -> Settings -> Advanced, enable "Allow the default Docker socket to be used (requires password)." |
| 273 | |
| 274 |  |
| 275 | |
| 276 | **Docker is now installed.** |
| 277 | |
| 278 | Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero) |
| 279 | |
| 280 | --- |
| 281 | |
| 282 | <a name="linux-installation"></a> |
| 283 | #### <img src="../res/setup/oses/linux.png" width="30" alt="Linux"/> Linux Installation |
| 284 | |
| 285 | **1.1. Choose Installation Method** |
| 286 | |
| 287 | You can install either Docker Desktop or docker-ce (Community Edition). |
| 288 | |
| 289 | **Option A: Docker Desktop (Recommended for beginners)** |
| 290 | |
| 291 | Follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/). |
| 292 | |
| 293 | **Option B: docker-ce (Lightweight alternative)** |
| 294 | |
| 295 | Follow the installation instructions [here](https://docs.docker.com/engine/install/). |
| 296 | |
| 297 | **1.2. Post-Installation Steps (docker-ce only)** |
| 298 | |
| 299 | If you installed docker-ce, add your user to the `docker` group: |
| 300 | |
| 301 | ```bash |
| 302 | sudo usermod -aG docker $USER |
| 303 | ``` |
| 304 | |
| 305 | Log out and back in, then authenticate: |
| 306 | |
| 307 | ```bash |
| 308 | docker login |
| 309 | ``` |
| 310 | |
| 311 | **1.3. Launch Docker** |
| 312 | |
| 313 | If you installed Docker Desktop, launch it from your applications menu. |
| 314 | |
| 315 | **Docker is now installed.** |
| 316 | |
| 317 | > [!TIP] |
| 318 | > **Deploying on a VPS/Server?** For production deployments with reverse proxy, SSL, and domain configuration, see the [VPS Deployment Guide](vps-deployment.md). |
| 319 | |
| 320 | --- |
| 321 | |
| 322 | ### Step 2: Run Agent Zero |
| 323 | |
| 324 | #### 2.1. Pull the Agent Zero Docker Image |
| 325 | |
| 326 | **Using Docker Desktop GUI:** |
| 327 | |
| 328 | - Search for `agent0ai/agent-zero` in Docker Desktop |
| 329 | - Click the `Pull` button |
| 330 | - The image will be downloaded to your machine in a few minutes |
| 331 | |
| 332 |  |
| 333 | |
| 334 | **Using Terminal:** |
| 335 | |
| 336 | ```bash |
| 337 | docker pull agent0ai/agent-zero |
| 338 | ``` |
| 339 | |
| 340 | #### 2.2. (Optional) Map Folders for Persistence |
| 341 | |
| 342 | Choose or create a folder on your computer where Agent Zero will save its data. |
| 343 | |
| 344 | Setting up persistence is needed only if you want your data and files to remain available even after you delete the container. |
| 345 | |
| 346 | You can pick any location you find convenient: |
| 347 | |
| 348 | - **Windows:** `C:\agent-zero-data` |
| 349 | - **macOS/Linux:** `/home/user/agent-zero-data` |
| 350 | |
| 351 | You can map just the `/a0/usr` directory (recommended) or individual subfolders of `/a0` to a local directory. |
| 352 | |
| 353 | > [!CAUTION] |
| 354 | > Do **not** map the entire `/a0` directory: it contains the application code and can break upgrades. |
| 355 | |
| 356 | > [!TIP] |
| 357 | > Choose a location that's easy to access and backup. All your Agent Zero data will be directly accessible in this directory. |
| 358 | |
| 359 | #### 2.3. Run the Container |
| 360 | |
| 361 | **Using Docker Desktop GUI:** |
| 362 | |
| 363 | - In Docker Desktop, go to the "Images" tab |
| 364 | - Click the `Run` button next to the `agent0ai/agent-zero` image |
| 365 | - Open the "Optional settings" menu |
| 366 | - **Ensure at least one host port is mapped to container port `80`** (set host port to `0` for automatic assignment) |
| 367 | - Click the `Run` button |
| 368 | |
| 369 |  |
| 370 |  |
| 371 | |
| 372 | The container will start and show in the "Containers" tab: |
| 373 | |
| 374 |  |
| 375 | |
| 376 | #### 2.4. Access the Web UI |
| 377 | |
| 378 | 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: |
| 379 | |
| 380 |  |
| 381 | |
| 382 | Open `http://localhost:<PORT>` in your browser. The Web UI will open - Agent Zero is ready for configuration! |
| 383 | |
| 384 |  |
| 385 | |
| 386 | > [!TIP] |
| 387 | > You can also access the Web UI by clicking the port link directly under the container ID in Docker Desktop. |
| 388 | |
| 389 | > [!NOTE] |
| 390 | > 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. |
| 391 | |
| 392 | **Running A0 using Terminal?** |
| 393 | |
| 394 | ```bash |
| 395 | docker run -p 0:80 -v /path/to/your/work_dir:/a0/usr agent0ai/agent-zero |
| 396 | ``` |
| 397 | |
| 398 | - Replace `0` with a fixed port if you prefer (e.g., `50080:80`) |
| 399 | |
| 400 | --- |
| 401 | |
| 402 | ## Step 3: Configure Agent Zero |
| 403 | |
| 404 | The UI opens on the welcome screen. If model setup is missing, send a message |
| 405 | or use the setup shortcuts to choose Cloud, AI account, or Local access, then |
| 406 | select your main and utility models. For the screenshot walkthrough, see the |
| 407 | [First-Run Onboarding guide](../guides/onboarding.md). |
| 408 | |
| 409 | ### Settings Configuration |
| 410 | |
| 411 | 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. |
| 412 | |
| 413 | ### Agent Configuration |
| 414 | |
| 415 | - **Agent Profile:** Select the default profile for new chats, such as `agent0`, |
| 416 | `hacker`, or `researcher`. |
| 417 | - **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances. |
| 418 | - **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding. |
| 419 | |
| 420 | See the [Agent Profiles guide](../guides/agent-profiles.md) for profile |
| 421 | switching, the Easy and Advanced editors, capability policy, and project |
| 422 | availability. |
| 423 | |
| 424 | > [!NOTE] |
| 425 | > Since v0.9.7, custom prompts belong inside a specific agent profile rather |
| 426 | > than a shared `/prompts` folder. Most users should use **Manage agents** and |
| 427 | > the Agent Editor instead of editing files directly. |
| 428 | |
| 429 | > [!NOTE] |
| 430 | > 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. |
| 431 | |
| 432 |  |
| 433 | |
| 434 | ### Chat Model Settings |
| 435 | |
| 436 | - **Provider:** Select the chat model provider (e.g., Anthropic) |
| 437 | - **Model Name:** Choose the specific model (e.g., claude-sonnet-4-5) |
| 438 | - **Context Length:** Set the maximum token limit for context window |
| 439 | - **Context Window Space:** Configure how much of the context window is dedicated to chat history |
| 440 | |
| 441 |  |
| 442 | |
| 443 | **Model naming is provider-specific.** |
| 444 | |
| 445 | 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". |
| 446 | |
| 447 | > [!TIP] |
| 448 | > **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. |
| 449 | |
| 450 | > [!TIP] |
| 451 | > **API URL:** URL of the API endpoint for the chat model - only needed for some providers like Ollama, LM Studio, Azure, etc. |
| 452 | |
| 453 | ### Utility Model Configuration |
| 454 | |
| 455 | - **Provider & Model:** Select a model for utility tasks like memory organization and summarization |
| 456 | - **Temperature:** Adjust the determinism of utility responses |
| 457 | |
| 458 | > [!NOTE] |
| 459 | > 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. |
| 460 | |
| 461 | ### Embedding Model Settings [Optional] |
| 462 | |
| 463 | - **Provider:** Choose the embedding model provider (e.g., OpenAI) |
| 464 | - **Model Name:** Select the specific embedding model (e.g., text-embedding-3-small) |
| 465 | |
| 466 | > [!NOTE] |
| 467 | > Agent Zero uses a local embedding model by default (runs on CPU), but you can switch to OpenAI embeddings like `text-embedding-3-small` or `text-embedding-3-large` if preferred. |
| 468 | |
| 469 | ### Built-in Voice Plugins |
| 470 | |
| 471 | - Agent Zero ships Whisper STT as the built-in `_whisper_stt` plugin and Kokoro TTS as the built-in `_kokoro_tts` plugin. |
| 472 | - Docker/bootstrap remains responsible for installing the required speech dependencies such as `ffmpeg`, Kokoro, Whisper, and `soundfile`. |
| 473 | - Both plugins can be enabled or disabled independently from the Agent Plugins section in the Web UI. |
| 474 | - Whisper model size, language, message handling, and silence behavior are configured from the plugin settings screen. |
| 475 | - If `_kokoro_tts` is disabled, spoken output falls back to the browser's native speech synthesis instead of the container runtime. |
| 476 | |
| 477 | ### API Keys |
| 478 | |
| 479 | Configure API keys for various service providers directly within the Web UI. Click `Save` to confirm your settings. |
| 480 | |
| 481 | > [!NOTE] |
| 482 | > **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. |
| 483 | |
| 484 | > [!TIP] |
| 485 | > 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. |
| 486 | |
| 487 | > [!CAUTION] |
| 488 | > **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. |
| 489 | |
| 490 | ### Authentication |
| 491 | |
| 492 | - **UI Login:** Set username for web interface access |
| 493 | - **UI Password:** Configure password for web interface security |
| 494 | - **Root Password:** Manage Docker container root password for SSH access |
| 495 | |
| 496 |  |
| 497 | |
| 498 | ### Development Settings |
| 499 | |
| 500 | - **RFC Parameters (local instances only):** Configure URLs and ports for remote function calls between instances |
| 501 | - **RFC Password:** Configure password for remote function calls |
| 502 | |
| 503 | Learn more about Remote Function Calls in the [Development Setup guide](dev-setup.md#step-6-configure-ssh-and-rfc-connection). |
| 504 | |
| 505 | > [!IMPORTANT] |
| 506 | > Always keep your API keys and passwords secure. |
| 507 | |
| 508 | > [!NOTE] |
| 509 | > On Windows host installs (non-Docker), you must use RFC to run shell code on the host system. The Docker runtime handles this automatically. |
| 510 | |
| 511 | --- |
| 512 | |
| 513 | ## Choosing Your LLMs |
| 514 | |
| 515 | 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: |
| 516 | |
| 517 | | LLM Role | Description | |
| 518 | | --- | --- | |
| 519 | | `chat_llm` | This is the primary LLM used for conversations, agent reasoning, and tool use. Vision support controls image understanding. | |
| 520 | | `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. | |
| 521 | | `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. | |
| 522 | |
| 523 | **How to Change:** |
| 524 | |
| 525 | 1. Open Settings page in the Web UI. |
| 526 | 2. Choose the provider for the LLM for each role (Main Model, Utility Model, Embedding Model) and write the model name. |
| 527 | 3. Click "Save" to apply the changes. |
| 528 | |
| 529 | > [!NOTE] |
| 530 | > The built-in Browser does not have a separate default model slot. The main agent decides when to call the direct `browser` tool. Browser settings can optionally choose a Browser LLM preset for Browser-owned helper operations. |
| 531 | |
| 532 | ### Important Considerations |
| 533 | |
| 534 | #### Model Naming by Provider |
| 535 | |
| 536 | Use the naming format required by your selected provider: |
| 537 | |
| 538 | | Provider | Model Name Format | Example | |
| 539 | | --- | --- | --- | |
| 540 | | OpenAI | Model name only | `claude-sonnet-4-5` | |
| 541 | | OpenRouter | Provider prefix mostly required | `anthropic/claude-sonnet-4-5` | |
| 542 | | Ollama | Model name only | `gpt-oss:20b` | |
| 543 | | oMLX | API-visible model name from `/v1/models` | `Qwen3-0.6B-4bit` | |
| 544 | | llama.cpp | API-visible model name from `/v1/models` or `--alias` | `local-gguf` | |
| 545 | | vLLM | Hugging Face model ID or served model alias | `Qwen/Qwen2.5-1.5B-Instruct` | |
| 546 | |
| 547 | > [!TIP] |
| 548 | > 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". |
| 549 | |
| 550 | #### Local Model Server Addresses From Docker |
| 551 | |
| 552 | When Agent Zero runs in Docker, `localhost` and `127.0.0.1` inside an API base URL mean the Agent Zero container, not your host machine. For a model server running on the host, use `http://host.docker.internal:<port>` when available, or the Docker host gateway address such as `http://172.17.0.1:<port>` on the default Linux bridge. |
| 553 | |
| 554 | If the model server only listens on host loopback, for example `127.0.0.1:<port>`, the container still cannot reach it through the gateway. Configure the local server to listen on a Docker-reachable address such as `0.0.0.0`, and keep that port limited to trusted clients. |
| 555 | |
| 556 | #### Context Window & Memory Split |
| 557 | |
| 558 | - Set the **total context window** (e.g., 100k) first. |
| 559 | - Then tune the **chat history portion** as a fraction of that total. |
| 560 | - Extremely large totals can make even small fractions very large; adjust thoughtfully. |
| 561 | |
| 562 | #### Utility Model Guidance |
| 563 | |
| 564 | - Utility models handle summarization and memory extraction. |
| 565 | - Very small models (about 4B) usually fail at reliable context extraction. |
| 566 | - Aim for ~70B class models or strong cloud "flash/mini" models for better results. |
| 567 | |
| 568 | #### Reasoning/Thinking Models |
| 569 | |
| 570 | - Reasoning can increase cost and latency. Some models perform better **without** reasoning. |
| 571 | - If a model supports it, disable reasoning via provider-specific parameters (e.g., Venice `disable_thinking=true`). |
| 572 | |
| 573 | --- |
| 574 | |
| 575 | ## Installing and Using oMLX (Apple Silicon Local Models) |
| 576 | |
| 577 | oMLX is a local inference server for Apple Silicon Macs. It serves MLX models through an OpenAI-compatible API and supports chat, embeddings, and model listing endpoints. |
| 578 | |
| 579 | > [!NOTE] |
| 580 | > oMLX requires Apple Silicon and macOS 15+. On 16 GB machines, start with small quantized MLX models. |
| 581 | |
| 582 | ### macOS oMLX Installation |
| 583 | |
| 584 | **Using Homebrew:** |
| 585 | |
| 586 | ```bash |
| 587 | brew tap jundot/omlx https://github.com/jundot/omlx |
| 588 | brew install omlx |
| 589 | omlx start |
| 590 | ``` |
| 591 | |
| 592 | **Using the macOS App:** |
| 593 | |
| 594 | Download the oMLX app from the [official website](https://omlx.ai/) and follow the welcome flow to choose a model directory, start the server, and download or discover models. |
| 595 | |
| 596 | By default, oMLX serves its OpenAI-compatible API at `http://localhost:8000/v1`. |
| 597 | |
| 598 | To run a foreground server with oMLX's paged SSD cache enabled: |
| 599 | |
| 600 | ```bash |
| 601 | omlx serve --model-dir ~/.omlx/models --paged-ssd-cache-dir ~/.omlx/cache |
| 602 | ``` |
| 603 | |
| 604 | ### Configuring oMLX in Agent Zero |
| 605 | |
| 606 | 1. Start oMLX and make sure at least one model is available in the oMLX dashboard or model directory. |
| 607 | 2. In Agent Zero Settings, choose **oMLX** as the Chat model, Utility model, or Embedding model provider. |
| 608 | 3. Use the model name shown by oMLX's model list or dashboard. |
| 609 | 4. Agent Zero includes Docker-friendly defaults for oMLX on the host at `http://host.docker.internal:8000/v1`. Override the API base URL only if your oMLX server runs somewhere else. |
| 610 | 5. Click `Save` to confirm your settings. |
| 611 | |
| 612 | > [!NOTE] |
| 613 | > If Agent Zero runs in Docker and oMLX runs on the Mac host, ensure port **8000** is reachable from the container. The shipped Docker Compose file maps `host.docker.internal` to the host gateway for Linux Docker. Docker Desktop for macOS provides this hostname automatically. |
| 614 | |
| 615 | --- |
| 616 | |
| 617 | ## Installing and Using llama.cpp (GGUF Local Models) |
| 618 | |
| 619 | llama.cpp provides `llama-server`, a lightweight OpenAI-compatible HTTP server for GGUF models. Agent Zero talks to it through the same `/v1` API used by OpenAI-compatible clients. |
| 620 | |
| 621 | ### macOS llama.cpp Installation |
| 622 | |
| 623 | **Using Homebrew:** |
| 624 | |
| 625 | ```bash |
| 626 | brew install llama.cpp |
| 627 | ``` |
| 628 | |
| 629 | Start a server with a downloaded GGUF model: |
| 630 | |
| 631 | ```bash |
| 632 | llama-server -m ~/models/model.gguf --port 8080 --alias local-gguf |
| 633 | ``` |
| 634 | |
| 635 | By default, Agent Zero expects llama.cpp at `http://host.docker.internal:8080/v1`. The model name can be the model path returned by `/v1/models`, but using `--alias` gives you a short stable name such as `local-gguf`. |
| 636 | |
| 637 | ### Configuring llama.cpp in Agent Zero |
| 638 | |
| 639 | 1. Start `llama-server` and confirm `http://localhost:8080/v1/models` returns your model. |
| 640 | 2. In Agent Zero Settings, choose **llama.cpp** as the Chat model, Utility model, or Embedding model provider. |
| 641 | 3. Use the model ID shown by `/v1/models`, or the alias you passed with `--alias`. |
| 642 | 4. Override the API base URL only if you started `llama-server` on another host or port. |
| 643 | 5. Click `Save` to confirm your settings. |
| 644 | |
| 645 | > [!NOTE] |
| 646 | > If Agent Zero runs in Docker and cannot reach a host-side `llama-server`, start the server on an address Docker can reach, for example `--host 0.0.0.0`, and keep the port firewalled to trusted clients. |
| 647 | |
| 648 | --- |
| 649 | |
| 650 | ## Installing and Using vLLM (Local OpenAI-Compatible Serving) |
| 651 | |
| 652 | vLLM is a high-throughput local inference server with an OpenAI-compatible API. It is most common on Linux GPU hosts, and can also run on Apple Silicon through the vLLM Apple Silicon path or vLLM-Metal. |
| 653 | |
| 654 | For Apple Silicon Macs, install and activate vLLM-Metal: |
| 655 | |
| 656 | ```bash |
| 657 | curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash |
| 658 | source ~/.venv-vllm-metal/bin/activate |
| 659 | ``` |
| 660 | |
| 661 | Start a basic OpenAI-compatible server: |
| 662 | |
| 663 | ```bash |
| 664 | vllm serve Qwen/Qwen2.5-1.5B-Instruct --host 0.0.0.0 --port 8000 |
| 665 | ``` |
| 666 | |
| 667 | By default, Agent Zero expects vLLM at `http://host.docker.internal:8000/v1`, matching vLLM's default HTTP port. If another local provider already uses port 8000, start vLLM on another port and update Agent Zero's API base, for example `http://host.docker.internal:8001/v1`. |
| 668 | |
| 669 | ### Configuring vLLM in Agent Zero |
| 670 | |
| 671 | 1. Start vLLM and confirm `http://localhost:8000/v1/models` returns the served model. |
| 672 | 2. In Agent Zero Settings, choose **vLLM** as the Chat model, Utility model, or Embedding model provider. |
| 673 | 3. Use the model ID returned by vLLM's model list endpoint. |
| 674 | 4. If you started vLLM with `--api-key`, enter the same key in the advanced provider settings or environment. |
| 675 | 5. Click `Save` to confirm your settings. |
| 676 | |
| 677 | > [!NOTE] |
| 678 | > vLLM serves one model at a time by default. Use a generation model for Chat and Utility slots, and a separate embedding-capable vLLM server if you want vLLM embeddings. |
| 679 | |
| 680 | --- |
| 681 | |
| 682 | ## Installing and Using Ollama (Local Models) |
| 683 | |
| 684 | Ollama is a powerful tool that allows you to run various large language models locally. |
| 685 | |
| 686 | --- |
| 687 | |
| 688 | <a name="windows-ollama-installation"></a> |
| 689 | ### <img src="../res/setup/oses/windows.png" width="30" alt="Windows"/> Windows Ollama Installation |
| 690 | |
| 691 | Download and install Ollama from the official website: |
| 692 | |
| 693 | <button>[Download Ollama Setup](https://ollama.com/download/OllamaSetup.exe)</button> |
| 694 | |
| 695 | Once installed, continue to [Pulling Models](#pulling-models). |
| 696 | |
| 697 | --- |
| 698 | |
| 699 | <a name="macos-ollama-installation"></a> |
| 700 | ### <img src="../res/setup/oses/apple.png" width="30" alt="macOS"/> macOS Ollama Installation |
| 701 | |
| 702 | **Using Homebrew:** |
| 703 | |
| 704 | ```bash |
| 705 | brew install ollama |
| 706 | ``` |
| 707 | |
| 708 | **Using Installer:** |
| 709 | |
| 710 | Download from the [official website](https://ollama.com/). |
| 711 | |
| 712 | Once installed, continue to [Pulling Models](#pulling-models). |
| 713 | |
| 714 | --- |
| 715 | |
| 716 | <a name="linux-ollama-installation"></a> |
| 717 | ### <img src="../res/setup/oses/linux.png" width="30" alt="Linux"/> Linux Ollama Installation |
| 718 | |
| 719 | Run the installation script: |
| 720 | |
| 721 | ```bash |
| 722 | curl -fsSL https://ollama.com/install.sh | sh |
| 723 | ``` |
| 724 | |
| 725 | Once installed, continue to [Pulling Models](#pulling-models). |
| 726 | |
| 727 | --- |
| 728 | |
| 729 | ### Pulling Models |
| 730 | |
| 731 | **Finding Model Names:** |
| 732 | |
| 733 | Visit the [Ollama model library](https://ollama.com/library) for a list of available models and their corresponding names. Ollama models are referenced by **model name only** (for example, `llama3.2`). |
| 734 | |
| 735 | **Pull a model:** |
| 736 | |
| 737 | ```bash |
| 738 | ollama pull <model-name> |
| 739 | ``` |
| 740 | |
| 741 | Replace `<model-name>` with the name of the model you want to use. For example: `ollama pull mistral-large` |
| 742 | |
| 743 | ### Configuring Ollama in Agent Zero |
| 744 | |
| 745 | 1. Once you've downloaded your model(s), select it in the Settings page of the GUI. |
| 746 | 2. Within the Chat model, Utility model, or Embedding model section, choose **Ollama** as provider. |
| 747 | 3. Write your model code as expected by Ollama, in the format `llama3.2` or `qwen2.5:7b` |
| 748 | 4. Agent Zero includes Docker-friendly defaults for Ollama on the host at `http://host.docker.internal:11434`. Override the API base URL only if your Ollama server runs somewhere else. |
| 749 | 5. Click `Save` to confirm your settings. |
| 750 | |
| 751 |  |
| 752 | |
| 753 | > [!NOTE] |
| 754 | > If Agent Zero runs in Docker and Ollama runs on the host, ensure port **11434** is reachable from the container. The shipped Docker Compose file maps `host.docker.internal` to the host gateway for Linux Docker. If both services are in the same Docker network, you can use `http://<container_name>:11434` instead of `host.docker.internal`. |
| 755 | |
| 756 | ### Managing Downloaded Models |
| 757 | |
| 758 | **Listing downloaded models:** |
| 759 | |
| 760 | ```bash |
| 761 | ollama list |
| 762 | ``` |
| 763 | |
| 764 | **Removing a model:** |
| 765 | |
| 766 | ```bash |
| 767 | ollama rm <model-name> |
| 768 | ``` |
| 769 | |
| 770 | > [!TIP] |
| 771 | > 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_gpu` instead of `faiss_cpu` for the memory. |
| 772 | |
| 773 | --- |
| 774 | |
| 775 | ## Using Agent Zero on Your Mobile Device |
| 776 | |
| 777 | Agent Zero can be accessed from mobile devices and other computers using the built-in **Tunnel feature**. |
| 778 | |
| 779 | ### Recommended: Using Tunnel (Remote Access) |
| 780 | |
| 781 | The Tunnel feature allows secure access to your Agent Zero instance from anywhere: |
| 782 | |
| 783 | 1. Open Settings in the Web UI |
| 784 | 2. Navigate to the **External Services** tab |
| 785 | 3. Click on **Flare Tunnel** in the navigation menu |
| 786 | 4. Click **Create Tunnel** to generate a secure HTTPS URL |
| 787 | 5. Share this URL to access Agent Zero from any device |
| 788 | |
| 789 | > [!IMPORTANT] |
| 790 | > **Security:** Always set a username and password in Settings -> Authentication before creating a tunnel to secure your instance on the internet. |
| 791 | |
| 792 | For complete details on tunnel configuration and security considerations, see the [Remote Access via Tunneling](../guides/usage.md#remote-access-via-tunneling) section in the Usage Guide. |
| 793 | |
| 794 | ### Alternative: Local Network Access |
| 795 | |
| 796 | If you prefer to keep access limited to your local network: |
| 797 | |
| 798 | 1. Find the mapped port in Docker Desktop (format: `<PORT>:80`, e.g., `32771:80`) |
| 799 | 2. Access from the same computer: `http://localhost:<PORT>` |
| 800 | 3. Access from other devices on the network: `http://<YOUR_COMPUTER_IP>:<PORT>` |
| 801 | |
| 802 | > [!TIP] |
| 803 | > Find your computer's IP address with `ipconfig` (Windows) or `ifconfig`/`ip addr` (macOS/Linux). It's usually in the format `192.168.x.x` or `10.0.x.x`. |
| 804 | |
| 805 | For developers or users who need to run Agent Zero directly on their system, see the [In-Depth Guide for Full Binaries Installation](dev-setup.md). |
| 806 | |
| 807 | --- |
| 808 | |
| 809 | ## Advanced: Automated Configuration via Environment Variables |
| 810 | |
| 811 | 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. |
| 812 | |
| 813 | **Usage:** |
| 814 | |
| 815 | Add variables to your `.env` file in the format: |
| 816 | |
| 817 | ```env |
| 818 | A0_SET_{setting_name}={value} |
| 819 | ``` |
| 820 | |
| 821 | **Examples:** |
| 822 | |
| 823 | ```env |
| 824 | # Model configuration |
| 825 | A0_SET_chat_model_provider=anthropic |
| 826 | A0_SET_chat_model_name=claude-3-5-sonnet-20241022 |
| 827 | A0_SET_chat_model_ctx_length=200000 |
| 828 | |
| 829 | # Memory settings |
| 830 | A0_SET_memory_recall_enabled=true |
| 831 | A0_SET_memory_recall_interval=5 |
| 832 | |
| 833 | # Agent configuration |
| 834 | A0_SET_agent_profile=custom |
| 835 | A0_SET_agent_memory_subdir=production |
| 836 | ``` |
| 837 | |
| 838 | **Docker usage:** |
| 839 | |
| 840 | When running Docker, you can pass these as environment variables: |
| 841 | |
| 842 | ```bash |
| 843 | docker run -p 50080:80 \ |
| 844 | -e A0_SET_chat_model_provider=anthropic \ |
| 845 | -e A0_SET_chat_model_name=claude-3-5-sonnet-20241022 \ |
| 846 | agent0ai/agent-zero |
| 847 | ``` |
| 848 | |
| 849 | **Notes:** |
| 850 | |
| 851 | - These provide initial default values when settings.json doesn't exist or when new settings are added to the application. Once a value is saved in settings.json, it takes precedence over these environment variables. |
| 852 | - Sensitive settings (API keys, passwords) use their existing environment variables |
| 853 | - Container/process restart required for changes to take effect |
| 854 | |
| 855 | --- |
| 856 | |
| 857 | ### Manual Migration (Legacy or Non-Docker) |
| 858 | |
| 859 | 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`. |
| 860 | |
| 861 | ## Conclusion |
| 862 | |
| 863 | 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. |
| 864 | |
| 865 | **Next Steps:** |
| 866 | |
| 867 | - For production server deployments, see the [VPS Deployment Guide](vps-deployment.md) |
| 868 | - For development setup and extensions, see the [Development Setup Guide](dev-setup.md) |
| 869 | - For remote access via tunnel, see [Remote Access via Tunneling](../guides/usage.md#remote-access-via-tunneling) |
| 870 | |
| 871 | If you encounter any issues during the installation process, please consult the [Troubleshooting section](../guides/troubleshooting.md) of this documentation or refer to the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community for assistance. |