Skip to content

installation.md

Latest commit

 

History

History
967 lines (640 loc) · 39.3 KB

installation.md

File metadata and controls

967 lines (640 loc) · 39.3 KB
Raw

Installation Guide

Install Agent Zero, connect a model, and get your first reply. On a desktop, start with Launcher. For a terminal or server, use A0 Install or Docker.

Quick Start (Recommended)

You need a supported AI account, a provider API key, or a local model server. Launcher helps set up Docker, which runs Agent Zero's Linux workspace.

A0 Launcher

1. Download and open Launcher. Choose your operating system, then your processor type. Apple Silicon means an M-series Mac; most other desktop and laptop computers use x64.

Downloads

Your computer Download Launcher v1.9
Windows x64 · ARM64
macOS Apple Silicon · Intel
Linux x64 · ARM64

On Linux, you may need to allow the AppImage to run as a program in its file properties first. See the v1.9 release notes.

2. Create and open Agent Zero. An Instance is a separate Agent Zero setup with its own chats, settings, and workspace. Follow any Docker setup prompt, then choose Download Agent Zero or Run Agent Zero. Keep latest and the persistent workspace selected, then click Create. Wait for Running, then click Open UI. Optional Host access can stay off.

See the Launcher guide for screenshots and storage options.

Send your first message

3. Send a small task from the welcome message box. Agent Zero creates the chat for you. Try:

Create a one-page Markdown plan for a 15-minute team kickoff.
Include a goal, three agenda items, and next steps.
Save it as /a0/usr/workdir/docs-demo-20261030/kickoff-plan.md.

Welcome screen with a message box and Quick Actions

Connect a model

4. Choose how to connect. If no model is configured, the chat holds your message and shows these choices:

Chat model gate with Cloud, account, local and provider-plugin choices

  • Cloud provider: connect with a provider API key.
  • AI account: sign in to a supported account. The Codex guide walks through ChatGPT account setup.
  • Local model: connect Ollama, LM Studio, or another model server. See local server addresses before connecting from Docker.

If your provider is missing, click the provider-plugin link below the choices, or Didn't find your provider? Click to look in the Plugin Hub under a grid. The OpenCode Go guide shows how to install a provider plugin, refresh the page, and choose its models.

Select the Main model for conversations and the Utility model for tasks such as summaries and chat names. You can use the same provider for both. Leave other settings at their defaults to begin with. Click Finish setup, then Continue on the final screen to close the wizard. The integrations offered there are optional.

Open your first result

5. Continue in the same chat. Your original message resumes when setup is saved; do not send it again. For the kickoff task, look for a reply and a link to kickoff-plan.md. Open the file to check it. Your plan may differ from this example.

Completed kickoff plan with tool activity and a link to the Markdown file

  • No reply? Check that setup finished and both models are available through your provider. Read any connection or account error shown in the chat.
  • A reply, but no file? Ask the agent to save the plan at the requested path and return a link.
  • Still stuck? Open the Troubleshooting guide.

Next, explore Browser, Desktop and documents, or Projects. You can also import chats from Pi, Hermes, or Claude Code.

Optional: work on your own computer

Agent Zero can work in its Linux workspace without access to the rest of your computer. When you want local files, commands, or a host browser, use Launcher Host access. Launcher maintains the supporting CLI for you. Choose the permissions you need.

For terminal chat or a connection from another computer, install A0 CLI on that computer and run a0. For a shared folder alone, see Use Local Folders.

Terminal and Docker installation

A0 Install

Use A0 Install when you want the command-line path. The installer creates a Dockerized Agent Zero instance, mounts user data to /a0/usr, and tries to reuse an existing Docker-compatible runtime before setting one up.

macOS / Linux

curl -fsSL https://bash.agent-zero.ai | bash

Windows PowerShell

irm https://ps.agent-zero.ai | iex

Headless / scripted

For servers and automation, Quick Start mode creates one instance and exits without opening menus:

curl -fsSL https://bash.agent-zero.ai | bash -s -- --quick-start --name agent-zero --port 5080
& ([scriptblock]::Create((irm https://ps.agent-zero.ai))) -QuickStart -Name agent-zero -Port 5080

Use --skip-runtime-setup / -SkipRuntimeSetup when Docker must already be working and the installer should not try to set up a runtime. See the A0 Install repository for all installer flags.

Open the URL printed by the installer. With port 5080 on your own computer, it is http://localhost:5080. For a remote server, follow the VPS guide for access and authentication.

Docker already installed? Run this directly

docker run -d -p 127.0.0.1:5080:80 -v a0_usr:/a0/usr agent0ai/agent-zero

Open http://localhost:5080 on the Docker host, then send your first message. If the port is occupied, replace 5080 with a free port and use it in your URL. This command makes the Web UI available only on that computer.

Persistent storage and backups

The command above uses the named Docker volume a0_usr for settings, chats, memory, projects, and custom plugins. Reuse that volume when replacing the container, and keep it separate from other running Instances. In Launcher, keep Persistent workspace selected, or choose a Docker volume in Workspace storage.

Persistent storage keeps data when a container is replaced. A backup gives you a separate copy to restore after mistakes or loss. Use both. Create a backup from Settings -> Check for Updates -> Backup & Restore, or from the Launcher Instance menu. See Use Local Folders if you want to use a host folder instead of a Docker volume.

How to Update Agent Zero

Self Update (Recommended)

Use the built-in updater in the Web UI:

  1. Open Settings UI -> Update tab
  2. Open Self Update
  3. Wait for the update checker to see if you have the latest version or if there's an available update.

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.

Updating from v1.20 to v2.0

Agent Zero v2.0 starts a new major release line. If your instance is on v1.20, the in-app Self Update can show the newer v2.x line, but it will not apply that jump inside the existing v1 Docker image. The safe path is:

  1. Create a backup zip from the old v1.20 instance.
  2. Pull the new agent0ai/agent-zero:latest Docker image. For the v2.0 release, latest is the v2.0 image.
  3. Start a new container from that image.
  4. Restore the backup zip into the new v2.0 instance.

Self Update warning for a newer major release line

Without Agent Zero Launcher

Use this path if you manage Agent Zero directly from Docker Desktop or Docker CLI.

  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.
  2. Pull the v2.0 image. In Docker Desktop, search for agent0ai/agent-zero:latest and pull that image. In Docker CLI, run: 
    docker pull agent0ai/agent-zero:latest
  3. Start a new v2.0 container on a different host port so the old instance stays available: 
    docker run -d -p 50081:80 --name agent-zero-v2 -v a0_v2_usr:/a0/usr agent0ai/agent-zero:latest
  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.
  5. Verify chats, projects, memory, settings, and custom plugins before removing the old v1.20 container.

With Agent Zero Launcher

Launcher gives you the same backup/restore idea from the Instances page.

  1. Open Instances, choose the old v1.20 Instance, and use Backup /a0/usr.
  2. Open Installs, use the latest card, then Install or Run the image. For the v2.0 release, latest is the v2.0 image.
  3. Return to Instances, choose the new v2.0 Instance, and use Restore /a0/usr with the backup zip.
  4. Open the new Instance and verify it before deleting or stopping the old v1.20 container.

Launcher keeps old and new Instances visible separately, which makes it easier to compare them before cleanup.

Caution

Do not try to solve the v1.20 -> v2.0 jump by bind-mounting the whole old /a0 directory into a new container. Keep user data under /a0/usr, use the backup/restore flow, and let the new image provide the v2.0 system files.

Updating from Pre-v0.9.8

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.

  1. Backup your existing usr/ directory (which contains your settings, projects, memory, and custom plugins).
  2. Run the new install script to set up the current Docker-based install:
    • macOS / Linux: curl -fsSL https://bash.agent-zero.ai | bash
    • Windows (PowerShell): irm https://ps.agent-zero.ai | iex
  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.
  4. Restart the container for the changes to take effect.

Manual Update (Advanced)

Use this only if Self Update is unavailable or you must manage containers yourself (for example, some custom Docker setups).

  1. Keep the current container running
  2. docker pull agent0ai/agent-zero:latest
  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
  4. On the old instance: Settings -> Check for Updates -> Backup & Restore -> Create Backup
  5. On the new instance: restore the downloaded backup zip
  6. Verify chats and data, then remove the old container

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.json and restart to regenerate default settings.

Manual Installation (Advanced)

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.

Step 1: Install Docker Desktop

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:

Windows
Windows 		macOS
macOS 		Linux
Linux

Windows Windows Installation

1.1. Download Docker Desktop

Go to the Docker Desktop download page and download the Windows version (Intel/AMD is the main download button).

docker download



1.2. Run the Installer

Run the installer with default settings.

docker install

docker install



1.3. Launch Docker Desktop

Once installed, launch Docker Desktop from your Start menu or desktop shortcut.

docker installed

Docker is now installed.

Continue to Step 2: Run Agent Zero

macOS macOS Installation

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).

docker download



1.2. Install Docker Desktop

Drag and drop the Docker application to your Applications folder.

docker install



1.3. Launch Docker Desktop

Open Docker Desktop from your Applications folder.

docker installed



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 socket macOS

Docker is now installed.

Continue to Step 2: Run Agent Zero

Linux Linux Installation

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.

Step 2: Run Agent Zero

2.1. Pull the Agent Zero Docker Image

Using Docker Desktop GUI:

  • Search for agent0ai/agent-zero in Docker Desktop
  • Click the Pull button
  • The image will be downloaded to your machine in a few minutes

docker pull

Using Terminal:

docker pull agent0ai/agent-zero

2.2. (Optional) Map Folders for Persistence

Create a dedicated folder on the Docker host, such as /home/user/agent-zero-data, and map it to /a0/usr inside the container. Docker calls this a bind mount. It keeps settings, chats, memory, projects, and custom plugins in that host folder even after you delete the container.

The two paths show the same files: /home/user/agent-zero-data/reports on the host is /a0/usr/reports to Agent Zero. Edits and deletions affect both sides. Without persistent storage, stopping the container keeps data, but deleting the container loses it. A named Docker volume is another persistence option, as used by the quick-start command above.

Caution

Do not map the entire /a0 directory: it contains the application code and can break upgrades.

See Use Local Folders With Agent Zero for Docker CLI, Docker Desktop, Compose, read-only access, and adding a separate work folder. In Launcher, use Workspace storage.

2.3. Run the Container

Using Docker Desktop GUI:

  • In Docker Desktop, go to the "Images" tab
  • Click the Run button next to the agent0ai/agent-zero image
  • Open the "Optional settings" menu
  • Ensure at least one host port is mapped to container port 80 (set host port to 0 for automatic assignment)
  • To use the folder from step 2.2, add it under Volumes: Host path = your local data folder, Container path = /a0/usr
  • Click the Run button

docker port mapping docker volume mapping

Using Terminal:

mkdir -p /home/user/agent-zero-data
docker run -d -p 127.0.0.1:5080:80 \
  --mount type=bind,source=/home/user/agent-zero-data,target=/a0/usr \
  agent0ai/agent-zero

Replace the host path with your own. This example opens at http://localhost:5080; choose another host port if it is already in use.

The container will start and show in the "Containers" tab:

docker containers

2.4. Access the Web UI

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:

docker logs

Open http://localhost:<PORT> in your browser. The Web UI will open - Agent Zero is ready for configuration!

docker ui

Tip

You can also access the Web UI by clicking the port link directly under the container ID in Docker Desktop.

Note

If you mapped /a0/usr, the chosen host folder contains Agent Zero user data. Application code remains inside the container. Local file edits are visible through the mount; settings changes may still require a reload or restart.

Step 3: Configure Agent Zero

For your first chat, follow Connect a model above. The First-Run Onboarding guide shows the complete wizard. The settings below are available when you want to change or fine-tune your setup later; you do not need to configure every section to get started.

Settings Configuration

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.

Agent Configuration

  • Agent Profile: Select the default profile for new chats, such as agent0, hacker, or researcher.
  • Memory Subdirectory: Select the subdirectory for agent memory storage, allowing separation between different instances.
  • Knowledge Subdirectory: Specify the location of custom knowledge files to enhance the agent's understanding.

See the Agent Profiles guide for profile switching, the Easy and Advanced editors, capability policy, and project availability.

Note

Since v0.9.7, custom prompts belong inside a specific agent profile rather than a shared /prompts folder. Most users should use Manage agents and the Agent Editor instead of editing files directly.

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.

settings

Chat Model Settings

  • Provider: Select the chat model provider (e.g., Anthropic)
  • Model Name: Choose the specific model (e.g., claude-sonnet-4-5)
  • Context Length: Set the maximum token limit for context window
  • Context Window Space: Configure how much of the context window is dedicated to chat history

chat model settings

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 " 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.

Utility Model Configuration

  • Provider & Model: Select a model for utility tasks like memory organization and summarization
  • Temperature: Adjust the determinism of utility responses

Note

Choose a Utility model that handles summaries and memory tasks reliably. Test it with your own work before switching to a smaller local model just to save resources.

Embedding Model Settings [Optional]

  • Provider: Choose the embedding model provider (e.g., OpenAI)
  • Model Name: Select the specific embedding model (e.g., text-embedding-3-small)

Note

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.

Built-in Voice Plugins

  • Agent Zero ships Whisper STT as the built-in _whisper_stt plugin and Kokoro TTS as the built-in _kokoro_tts plugin.
  • Docker/bootstrap remains responsible for installing the required speech dependencies such as ffmpeg, Kokoro, Whisper, and soundfile.
  • Both plugins can be enabled or disabled independently from the Agent Plugins section in the Web UI.
  • Whisper model size, language, message handling, and silence behavior are configured from the plugin settings screen.
  • If _kokoro_tts is disabled, spoken output falls back to the browser's native speech synthesis instead of the container runtime.

API Keys

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.

Authentication

  • UI Login: Set username for web interface access
  • UI Password: Configure password for web interface security
  • Root Password: Manage Docker container root password for SSH access

settings

Development Settings

  • RFC Parameters (local instances only): Configure URLs and ports for remote function calls between instances
  • RFC Password: Configure password for remote function calls

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.

Choosing your models

In Settings, you can choose different models for different jobs:

Model What it does
Main Handles your conversations and uses tools to do the work. Choose a model with image support if you want it to understand pictures.
Utility Handles summaries, chat names, and memory tasks.
Embedding Helps find relevant memory and knowledge. The default runs locally on the CPU. Changing it requires rebuilding the memory index.

How to Change:

  1. Open Settings page in the Web UI.
  2. Choose the provider and model for Main, Utility, or Embedding.
  3. Click "Save" to apply the changes.

Note

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.

Important Considerations

Model Naming by Provider

Use the naming format required by your selected provider. These are naming examples, not model recommendations:

Provider Model Name Format Example
Anthropic Model name only claude-sonnet-4-5
OpenRouter Provider prefix mostly required anthropic/claude-sonnet-4-5
Ollama Model name only gpt-oss:20b
oMLX API-visible model name from /v1/models Qwen3-0.6B-4bit
llama.cpp API-visible model name from /v1/models or --alias local-gguf
vLLM Hugging Face model ID or served model alias Qwen/Qwen2.5-1.5B-Instruct

Tip

If you see "Invalid model ID," verify the provider and naming format on the provider website, or search the web for " model naming".

Local Model Server Addresses From Docker

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.

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.

Context Window & Memory Split

  • Set the total context window (e.g., 100k) first.
  • Then tune the chat history portion as a fraction of that total.
  • Extremely large totals can make even small fractions very large; adjust thoughtfully.

Utility Model Guidance

  • Utility models handle summarization and memory extraction.
  • Check that your chosen model produces useful summaries and memories with your own work.
  • A smaller local model may use fewer resources, but loading successfully does not establish that it can handle those tasks.

Reasoning/Thinking Models

  • Reasoning can increase cost and latency. Some models perform better without reasoning.
  • If a model supports it, disable reasoning via provider-specific parameters (e.g., Venice disable_thinking=true).

Installing and Using oMLX (Apple Silicon Local Models)

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.

Note

oMLX requires Apple Silicon and macOS 15+. On 16 GB machines, start with small quantized MLX models.

macOS oMLX Installation

Using Homebrew:

brew tap jundot/omlx https://github.com/jundot/omlx
brew install omlx
omlx start

Using the macOS App:

Download the oMLX app from the official website and follow the welcome flow to choose a model directory, start the server, and download or discover models.

By default, oMLX serves its OpenAI-compatible API at http://localhost:8000/v1.

To run a foreground server with oMLX's paged SSD cache enabled:

omlx serve --model-dir ~/.omlx/models --paged-ssd-cache-dir ~/.omlx/cache

Configuring oMLX in Agent Zero

  1. Start oMLX and make sure at least one model is available in the oMLX dashboard or model directory.
  2. In Agent Zero Settings, choose oMLX as the Chat model, Utility model, or Embedding model provider.
  3. Use the model name shown by oMLX's model list or dashboard.
  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.
  5. Click Save to confirm your settings.

Note

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.

Installing and Using llama.cpp (GGUF Local Models)

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.

macOS llama.cpp Installation

Using Homebrew:

brew install llama.cpp

Start a server with a downloaded GGUF model:

llama-server -m ~/models/model.gguf --port 8080 --alias local-gguf

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.

Configuring llama.cpp in Agent Zero

  1. Start llama-server and confirm http://localhost:8080/v1/models returns your model.
  2. In Agent Zero Settings, choose llama.cpp as the Chat model, Utility model, or Embedding model provider.
  3. Use the model ID shown by /v1/models, or the alias you passed with --alias.
  4. Override the API base URL only if you started llama-server on another host or port.
  5. Click Save to confirm your settings.

Note

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.

Installing and Using vLLM (Local OpenAI-Compatible Serving)

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.

For Apple Silicon Macs, install and activate vLLM-Metal:

curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash
source ~/.venv-vllm-metal/bin/activate

Start a basic OpenAI-compatible server:

vllm serve Qwen/Qwen2.5-1.5B-Instruct --host 0.0.0.0 --port 8000

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.

Configuring vLLM in Agent Zero

  1. Start vLLM and confirm http://localhost:8000/v1/models returns the served model.
  2. In Agent Zero Settings, choose vLLM as the Chat model, Utility model, or Embedding model provider.
  3. Use the model ID returned by vLLM's model list endpoint.
  4. If you started vLLM with --api-key, enter the same key in the advanced provider settings or environment.
  5. Click Save to confirm your settings.

Note

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.

Installing and Using Ollama (Local Models)

Ollama is a powerful tool that allows you to run various large language models locally.

Windows Windows Ollama Installation

Download and install Ollama from the official website:

Download Ollama Setup

Once installed, continue to Pulling Models.

macOS macOS Ollama Installation

Using Homebrew:

brew install ollama

Using Installer:

Download from the official website.

Once installed, continue to Pulling Models.

Linux Linux Ollama Installation

Run the installation script:

curl -fsSL https://ollama.com/install.sh | sh

Once installed, continue to Pulling Models.

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

Configuring Ollama in Agent Zero

  1. Once you've downloaded your model(s), select it in the Settings page of the GUI.
  2. Within the Chat model, Utility model, or Embedding model section, choose Ollama as provider.
  3. Write your model code as expected by Ollama, in the format llama3.2 or qwen2.5:7b
  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.
  5. Click Save to confirm your settings.

ollama

Note

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.

Managing Downloaded Models

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_gpu instead of faiss_cpu for the memory.

Using Agent Zero on Your Mobile Device

Agent Zero can be accessed from mobile devices and other computers using the built-in Tunnel feature.

Recommended: Using Tunnel (Remote Access)

The Tunnel feature allows secure access to your Agent Zero instance from anywhere:

  1. Open Settings in the Web UI
  2. Navigate to the External Services tab
  3. Click on Flare Tunnel in the navigation menu
  4. Click Create Tunnel to generate a secure HTTPS URL
  5. Share this URL to access Agent Zero from any device

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.

Alternative: Local Network Access

If you prefer to keep access limited to your local network:

  1. Find the mapped port in Docker Desktop (format: <PORT>:80, e.g., 32771:80)
  2. Access from the same computer: http://localhost:<PORT>
  3. Access from other devices on the network: http://<YOUR_COMPUTER_IP>:<PORT>

Tip

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.

For developers or users who need to run Agent Zero directly on their system, see the In-Depth Guide for Full Binaries Installation.

Advanced: Automated Configuration via Environment Variables

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 -d -p 127.0.0.1:5080:80 -v a0_usr:/a0/usr \
  -e A0_SET_chat_model_provider=anthropic \
  -e A0_SET_chat_model_name=claude-3-5-sonnet-20241022 \
  agent0ai/agent-zero

Notes:

  • Open http://localhost:5080 on the Docker host after startup. This example binds to that computer only.
  • 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.
  • Sensitive settings (API keys, passwords) use their existing environment variables
  • Container/process restart required for changes to take effect

Manual Migration (Legacy or Non-Docker)

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.

Conclusion

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.