Agent Zero

Last reviewed Aug 26, 2026 · 914 words

Agent Zero is the framework to try when you want to watch a language model actually do work on a computer, and the thing to understand before the first docker run is that it will run whatever shell commands it decides are necessary. That is the design: the agent's tools are a terminal, a code interpreter, a browser and a search engine, and it plans, executes, reads the output and tries again, spawning subordinate agents for subtasks. Everything about its behaviour lives in editable prompt files, so unlike most agent products you can read exactly why it did something. It needs a capable model to be useful, it needs Docker isolation to be safe, and it needs you in the loop. In my experience all three are non-negotiable, and this guide is organised around them.

One container, one volume, one port

The project ships a single image that bundles the web UI, the agent runtime and the execution environment the agent works inside:

mkdir -p ~/agent-zero
docker run -d --name agent-zero \
  -p 50001:80 \
  -v ~/agent-zero:/a0 \
  frdel/agent-zero-run:latest

The web UI comes up on port 50001, and the /a0 mount is where prompts, memory, settings and the agent's working files persist across updates. The 2 GB of RAM is the floor for the container itself; add whatever the model needs if you serve it locally on the same box. Bind the port to a LAN or VPN address. The UI has authentication you can set in its settings, but a service that can execute arbitrary commands should not be reachable from the internet regardless.

The model choice decides whether it works at all

Agent Zero speaks to any OpenAI-compatible endpoint and to Ollama directly, and it splits duties across a chat model, a utility model for cheap housekeeping calls, and an embedding model for memory. That split is the cost lever. Put a frontier model on the chat role and a small local model on the utility role and the bill stays sane. What does not work is a small local model on the chat role: tool calling, multi-step planning and recovering from a failed command are exactly where 7B and 8B models fall apart, and the result is an agent that loops. Local models in the 30B-plus class with strong tool-use training can hold up for bounded tasks; anything smaller is a demo. The AI LLM runners category covers what it takes to serve those on your own hardware, and the VRAM math post tells you whether your GPU can.

Editable prompts are the real feature

Under /a0/prompts sit the system prompts, tool descriptions and behaviour rules as plain Markdown. Agent Zero reads them at runtime, so changing how the agent introduces itself, what it refuses, how it delegates to subordinates or which tools it prefers is a text edit, no rebuild. Behaviour adjustments made in the UI also land as files. Two practical uses: give it a house style for the scripts it writes, and tell it about your environment (that the box has no GPU, that /data is the only writable share) so it stops guessing. Persistent memory, stored as embeddings in the same volume, lets it recall solutions across sessions, which is helpful and occasionally means it confidently reuses a wrong one.

Isolation is the safety model, so do not weaken it

The agent executes commands inside the container, which is what makes "let it run" tolerable. Resist the two common temptations. Do not mount your home directory or the Docker socket into it so it can "do more"; give it a scratch volume and copy results out. Do not hand it credentials to production systems in the first week. Treat it as a capable intern with root on a throwaway VM: useful for research, data wrangling, writing and testing scripts, and setting up sandboxes, and dangerous only in proportion to what you connect it to. The prompt injection defence post explains the failure mode that matters here: a web page the agent reads can instruct it, and it will sometimes obey.

Supervision is a workload, not a checkbox

Autonomy in Agent Zero means it keeps going. It asks for input when it is stuck, but a bad plan can burn 40 tool calls before it notices. Watch the first sessions on any new kind of task, set spending limits at the API provider, and keep tasks small enough that a wrong turn costs minutes. Used that way it does real work. Left alone with a broad goal and an open API key, it does expensive work of uncertain value.

What I'd do

Run the container on a VM with nothing else on it, volume at /a0, port reachable over Tailscale only. Chat model from a frontier API with a hard monthly cap, utility and embedding models from Ollama on the same host. Edit the prompts to describe your environment before the first task, and start with bounded jobs: "profile this CSV and write a summary", "write and test a script that rotates these logs". Review every session for the first month. For someone who wants to learn how agents actually behave, and to control every line of that behaviour, it is the most transparent option available; for unattended automation it is not there yet, and neither is anything else.