Agent Zero with Ollama: Docker installation and limites

#What Agent Zero is

Agent Zero (repository agent0ai/agent-zero) presents itself as a framework that gives the agent a complete Linux computer: an XFCE desktop in a Docker container, a browser with DOM annotation, live coworking on Markdown files, spreadsheets, and presentations, and a hub of more than 100 community plugins. The project had more than 19,000 stars on GitHub as of September 28, 2026, with the latest version, tagged v2.13, published on September 23, 2026.

This is not a specialized coding agent in the sense of OpenCode or Cline: Agent Zero targets cross-functional tasks (research, desktop application control, web interface review, analysis) at the cost of heavier infrastructure than a simple terminal binary.

The project also highlights “agent profiles” (specialists created on the fly, for example for a cautious financial analysis with spreadsheet deliverables), project management that isolates files, secrets, memories, and repositories by context, and multi-agent collaboration in which a lead agent delegates research, coding, analysis, or review to dedicated subagents. Each of these features consumes context and instruction-following capacity, which directly affects model choice once you move beyond simple chat.

#Install the Docker container

With Docker already installed, the most direct route is a single command that mounts the instance data in a persistent volume. The project also offers a script installer (A0 Install) for servers and headless mode, as well as a graphical launcher (A0 Launcher) that manages Docker, instances, and ports for you.

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

Once the container is running, the web interface opens on the selected port (80 by default, or the one passed as a parameter) to configure the model provider before the first task. On a server without a graphical interface, the script installer supports a silent mode that creates a specified instance and port without opening a menu, which is useful for automated deployment or a remote machine accessible only through SSH.

#Connect a local Ollama

The official installation documentation explains the process in detail: in the settings for the conversation model, utility model, or embedding model, choose Ollama as the provider, enter the model name expected by Ollama (for example, llama3.2 or qwen2.5:7b), then enter the API URL if it differs from the default value.

If the container cannot connect to Ollama, the documentation notes that port 11434 must be reachable from the container; the provided Docker Compose file maps host.docker.internal to the host gateway under Docker on Linux, and if both services share the same Docker network, the address can also be http://(nom from the container):11434.

#Which model to choose, and for what role

Agent Zero distinguishes three model slots: chat (main conversation), utility (memory organization, summarization), and embedding (memory search). The model name format depends on the provider: with Ollama, it is the model name alone (gpt-oss:20b), without a provider prefix unlike OpenRouter.

The most commonly overlooked point: a decent conversational model can fail in a utility role if it is too small, silently degrading memory quality without the user understanding why the agent “forgets” or confuses facts from one session to the next.

#Tool calling with a small local model

Agent Zero documents a widespread problem with lightweight local models: the model explains the command instead of calling the tool that would execute it. The project proposes a prompt-only fix, without touching the code: the “Tiny Local” profile, which retains the standard tool-call format but removes visible reasoning fields from the communication prompt, asking only for an executable JSON object with tool_name and tool_args.

An alternative that does not change the profile is to add a dedicated prompt file (the .promptinclude.md extension) that repeats the expected discipline: a visible response that is exactly a JSON object with exactly the fields tool_name and tool_args, with no Markdown formatting or text before or after it. The documentation is explicit about this fix’s limitation: it is a prompt and profile adjustment, not a change to the execution code — if a specific model continues to fail despite this discipline, the next step is to change models, not make the prompt even more complex.

#What the Linux desktop really changes

What sets Agent Zero apart from purely terminal-based agents is this complete XFCE desktop inside the container: the agent can open a real graphical application (Blender to model an object, a file manager, a visible terminal), and the user can observe every action while sharing the same virtual mouse and keyboard, with the ability to intervene at any time.

The built-in browser goes beyond simple page control: Annotate mode turns any web page into a surface of clickable instructions—change an element, inspect it, reuse it in another project, or leave a targeted comment that the agent then handles as a task.

#Connect MCP servers

Beyond its built-in tools (browser, terminal, files), Agent Zero can connect to external MCP servers to reach other services: the official documentation describes each MCP connection as a bridge—one can connect Gmail, another a database, and another an automation tool. An MCP server is declared either as a command run locally or as a remote URL, which changes the networking question: a command local to the container faces the same constraints as access to Ollama (host.docker.internal, shared Docker network), while a remote URL follows the container's normal network rules.

The documentation recommends limiting each connection to what is strictly necessary rather than adding connections as a precaution: every connected MCP server expands the surface the model can reach, including with a local model whose tool-calling behavior is less predictable than that of a high-end cloud model.

#Security checklist before connecting the model and tools

Three areas deserve explicit verification before letting Agent Zero operate without constant supervision: container isolation, secrets and API keys, and connected MCP servers.

#Compared with other local agents

• OpenCode with Ollama in the terminal

#Limitations to know before getting started

Misleading search volume

“Agent Zero” also refers to entertainment content in search engines; actual demand for the development framework is narrower than the raw keyword volume suggests.

Disk and RAM footprint

The container includes a full desktop in addition to the agent runtime: plan for more resources than with a minimal CLI agent, even if inference itself runs elsewhere via Ollama.

Undersized utility model

An undersized utility model degrades memory without an explicit error message; it’s the first thing to check if the agent seems to “lose the thread” from one session to the next.

Network internal to the container

host.docker.internal works with Docker Desktop and the provided Linux configuration, but a custom deployment (custom Docker network, remote hosting) requires entering the API URL manually again.

• Deploy an LLM in production with Docker Compose
• Install Ollama with Docker
• AI agent: general definitions and limitations
• Source: official Agent Zero GitHub repository
• Source: official installation guide
• Source: official guide to local tool calling