How to Run Agent Zero Locally on Mac

Agent Zero is an open-source agent framework that runs in a Docker container and works through a web UI. This guide shows how to run Agent Zero locally on Mac, on your own machine or on a dedicated Mac in the cloud.

How Agent Zero runs

The project lives at github.com/agent0ai/agent-zero. Unlike a terminal coding agent, Agent Zero is a full environment: the agent, its tools and its web UI all run inside one container, and the agent can execute code in that container. Three facts from the docs shape everything below:

• It runs in Docker. The README says it runs wherever Docker runs.
• The web UI is on container port 80. You map it to any host port you like.
• Your data lives in /a0/usr. That is the one path you should persist.

Agent Zero is an independent project. Hatmac is not affiliated with it.

Docker on Apple silicon

The Agent Zero installation guide is written around Docker Desktop on macOS, with Apple silicon covered.

• Docker Desktop. Download the Apple silicon build from Docker's install page. Docker supports the current and two previous major macOS releases and asks for at least 4GB of RAM. Rosetta 2 is recommended for some optional tools: softwareupdate --install-rosetta. Agent Zero's guide also asks you to enable "Allow the default Docker socket to be used" under Settings, Advanced. Note Docker's licence: commercial use in larger enterprises needs a paid subscription.
• Colima. A command-line alternative that supports Apple silicon. Install it with brew install colima docker and start a VM with enough memory, for example colima start --cpu 4 --memory 8. Agent Zero's docs do not cover Colima, so details such as reaching services on the host may differ from Docker Desktop.

On a headless cloud Mac, Docker Desktop needs a one-time setup in the graphical session, which you can do over Screen Sharing or another remote desktop. See how to access a remote Mac for the options.

How to run Agent Zero locally on Mac

There are two documented routes.

The installer

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

The quickstart says this script handles Docker detection, pulling the image and creating the container. It prompts for a port and for authentication, then prints the web UI address. Read a script before piping it to your shell, as with any installer.

Plain Docker

If Docker is already running, the README gives this one-liner:

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

On a Mac that is reachable from the internet, change two things. Use a high port, and bind it to localhost so nothing outside the machine can reach it:

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

Then open http://localhost:5080. The -d flag keeps the container running in the background, so there is no need for tmux here. The named volume keeps your data if the container is removed or recreated.

Connect models: Ollama or APIs

Agent Zero asks for a main chat model and a utility model for internal tasks such as memory. The docs suggest a strong main model and a fast utility model, and warn that very small models (about 4B) often fail at the utility work.

Cloud APIs

Enter keys in the web UI settings and save. For OpenAI-compatible providers, add the key under External Services, Other OpenAI-compatible API keys, then choose OpenAI Compatible as the provider. The docs point out that a ChatGPT Plus subscription does not include API credits.

Local models with Ollama

Run Ollama natively on macOS, not in a container, so it can use the Apple silicon GPU through Metal.

brew install ollama
ollama serve
# in another terminal
ollama pull qwen2.5:7b

In Agent Zero settings, pick Ollama as the provider and enter the model name. By default Agent Zero looks for Ollama at http://host.docker.internal:11434, which reaches the host from inside the container. Change the base URL only if Ollama runs somewhere else. For a long-running setup, see running Ollama as a Mac mini server. The docs also mention oMLX as a local option on Apple silicon with macOS 15 or later.

Persistence and updates

• Map only /a0/usr. The docs warn not to map the whole /a0 directory, because it contains the application code and can break upgrades.
• Use a named volume or a folder. -v a0_usr:/a0/usr keeps data in a Docker volume that survives container removal.
• Update from the UI. The recommended path is Settings, Update, Self Update. The manual path is to pull the latest image, start a new container on a different port, back up from the old instance, restore into the new one, check it, and remove the old container.
• Snapshots are not backups. Agent Zero's Time Travel snapshots /a0/usr workspaces, but the README says it does not replace Git or backups. Push code to a remote and back up the volume.

Major version jumps can need the backup and restore route rather than the in-app updater. Check the installation guide before upgrading.

Secure the web UI

Agent Zero can run code and browse. Anyone who reaches its web UI can drive it. Treat it like a root shell.

1. Set a login. In Settings, Authentication, set a UI Login and a UI Password. The docs say to do this before creating any tunnel.
2. Bind to localhost. Use -p 127.0.0.1:5080:80 as above, never a bare -p 80:80 on a public machine.
3. Reach it through SSH. From your laptop:

ssh -N -L 5080:127.0.0.1:5080 you@your-mac

Then open http://localhost:5080 in your local browser. The traffic travels inside SSH, and the port is never open to the internet. Keep Ollama on its default local address as well rather than opening port 11434 to the network.

Resource needs and which plan

Memory is shared between macOS, the Docker VM, the Agent Zero container and any local model. Where the model runs decides the plan.

Setup	Rough fit
Cloud API models only	Mac mini M4 or M6, 16GB
Small local utility model plus cloud main model	Mac mini M6, 24GB
Local models around the 30B class	Mac Studio M5 Max, 36GB
70B-class local models	Mac Studio M5 Ultra, 96GB

These follow a simple rule of thumb: a 4-bit model needs roughly 0.5 to 0.7 GB per billion parameters plus room for context, and macOS lets the GPU use roughly two-thirds to three-quarters of unified memory by default. Leave a few gigabytes for the Docker VM on top. Agent Zero's docs say 70B-class models or strong cloud models work best, which makes the Mac Studio M5 Ultra the natural choice for a fully local setup. Read local LLMs and Apple silicon memory for more detail.

Prices in USD per month for each machine's starting configuration. More memory, storage or several machines? Ask us.

Agent Zero is one of several agents you can host on a dedicated Mac. Compare approaches in AI agents on Mac mini, or see Claude Code on Mac mini for a terminal agent. Need more memory than a standard configuration? Tell us what you need.