# Agent Zero documentation summary

Source: https://www.agent-zero.ai/p/docs/

Agent Zero is a personal, organic agentic framework with a Web UI, Docker runtime, Browser and Desktop Canvas surfaces, projects, memory, plugins, skills, model presets, scheduled tasks, and optional host-machine connectivity through A0 CLI. These docs are intentionally practical: what to open, what to click, where user-owned files belong, and when to use each feature.

For source-linked architecture and internals, use DeepWiki: https://deepwiki.com/agent0ai/agent-zero

## README capability map

Source: https://github.com/agent0ai/agent-zero/blob/main/README.md

Agent Zero is best described as a Docker-hosted Linux agent workbench: one container provides the Web UI, a real Linux desktop, a built-in Browser, document cowork surfaces, projects, memory, plugins, skills, and model routing. Use this map when routing a user to the right guide:

- Desktop Canvas: a real XFCE Linux desktop in the container for GUI applications, file work, terminals, and LibreOffice. The user can watch and intervene.
- Browser Canvas: built-in browsing for pages, screenshots, forms, downloads, extensions, and Annotate mode, where a user can click page elements to send precise change, inspect, lift, or comment instructions.
- Document cowork: Markdown Editor for plans, TODOs, notes, RFCs, and project handoffs; LibreOffice Writer, Calc, and Impress for ODT, ODS, and ODP files.
- Plugin Hub and customization: more than 100 community plugins plus local plugins, custom prompts, custom tools, MCP servers, A2A connectors, and project-scoped configuration.
- A0 CLI Connector: a host-side bridge for local files, shell workflows, real repositories, and approved host browser control while Agent Zero remains isolated in Docker.
- Projects, Skills, Agent Profiles, and Model Presets: use projects for isolated workspaces and secrets, skills for focused procedures, profiles for chat behavior, and presets for quick model setup changes.
- Subagents: Agent Zero can create subordinate agents for focused research, coding, writing, review, or verification work.
- Time Travel: Agent Zero-owned `/a0/usr` workspaces can have snapshot history, diff inspection, travel, and revert; it is a recovery layer, not a Git or backup replacement.

README safety reminders: keep Agent Zero in Docker or another isolated environment, do not mount an entire home directory unless the risk is understood, grant A0 CLI host access only for trusted machines and workspaces, store credentials in Secrets or project secrets, review actions touching accounts/money/production/private data, and keep backups for important workspaces.

## User-owned customization rule

For profiles, prompts, plugins, projects, and similar customizations, prefer `usr` paths. Rule of thumb: if something in `/a0/usr` has the same ID as something in the root `/a0` area, the user-owned version replaces or extends the root version. Keep root files as the base install and put user edits under `/a0/usr`.

## Installation

Source: https://www.agent-zero.ai/p/docs/installation/

For desktop use, start with [Agent Zero Launcher](https://www.agent-zero.ai/p/docs/launcher/): download it, create your first Instance, then select Open UI. Complete model setup through onboarding.

If you are already in a terminal or deploying to a server, use A0 Install:

- Windows PowerShell: `irm https://ps.agent-zero.ai | iex`
- macOS/Linux: `curl -fsSL https://bash.agent-zero.ai | bash`

After setup, complete onboarding and configure at least one model provider. Use the guided onboarding path for OpenRouter, our proxy API, or another compatible provider. The installation guide also covers local models, data persistence, backups, updates, and safe sharing.

## First-Run Onboarding

Source: https://www.agent-zero.ai/p/docs/onboarding/

The onboarding wizard asks how Agent Zero should use AI models:

- Choose Cloud for API-key or account-based providers.
- Choose Local for a local LLM running on your own machine, such as Ollama.
- For Ollama, start Ollama first, pull the exact model name such as `gemma4:26b`, and use `http://host.docker.internal:11434` if Docker needs to reach Ollama on the host.
- Pick a provider.
- Add an API key or connect an account.
- Choose a main model.
- Choose a utility model, which may be the same provider/model or a different provider/model.
- Finish and start chatting.

Useful anchors:

- https://www.agent-zero.ai/p/docs/onboarding/#choose-cloud-or-local
- https://www.agent-zero.ai/p/docs/onboarding/#pick-provider
- https://www.agent-zero.ai/p/docs/onboarding/#add-key-and-main-model
- https://www.agent-zero.ai/p/docs/onboarding/#choose-utility-model

## A0 CLI Connector

Source: https://www.agent-zero.ai/p/docs/a0-cli-connector/

A0 CLI connects the host terminal to Agent Zero. Agent Zero still does the thinking; the CLI is the doorway that lets it work on the machine where the CLI is running. Agent Zero stays in Docker. A0 CLI installs on the host machine.

Install commands:

- macOS/Linux: `curl -LsSf https://cli.agent-zero.ai/install.sh | sh`
- Windows PowerShell: `irm https://cli.agent-zero.ai/install.ps1 | iex`

Run `a0`, connect to a discovered local Agent Zero instance, or enter the Web UI URL manually. The connected shell shows the active host, project, model, local folder, Agent Zero workspace, and message box. Use `Ctrl+P` for the command palette if terminal function keys are captured.

Common commands include `/new`, `/chats`, `/project`, `/profile`, `/presets`, `/models`, `/browser`, `/attach`, `/pause`, `/resume`, and `/nudge`.

A0 CLI can also support Bring Your Own Browser mode. Keep the CLI connected, choose Bring Your Own Browser in Browser settings, and approve remote debugging only for a browser instance you trust Agent Zero to control. Once enabled, the host browser can be controlled from A0 CLI or from the Agent Zero Web UI Browser settings. Use `/browser relaunch` in A0 CLI to manually open or relaunch the host browser and trigger the approval prompt.

## Browser

Source: https://www.agent-zero.ai/p/docs/browser/

The Browser guide covers the right-side Browser Canvas surface and the Browser tool. Open the Canvas, select Browser, and click Open Browser or the plus button. The focused Browser surface shows tabs, navigation controls, address bar, annotation mode, and settings.

Use Browser for research, forms, screenshots, UI review, downloads, and real web pages. Annotate mode lets users point to a page area and send a targeted comment back into chat. Browser settings control Docker browser mode, host-browser mode, page content access, starting page, autofocus, and extensions.

## Desktop

Source: https://www.agent-zero.ai/p/docs/desktop/

The Desktop Canvas opens a Linux desktop inside Agent Zero. Use it for GUI applications, file inspection, and LibreOffice Cowork. The Desktop page is practical: when to use Desktop, how to open it from Canvas, how files are created or opened, and how Cowork helps the user and agent work in the same document.

## Projects

Source: https://www.agent-zero.ai/p/docs/projects/

Projects tell Agent Zero what world it is working in. Use one when a chat needs its own purpose, instructions, files, memory, secrets, variables, Git repository, or model choices.

Create a project when context should not leak into every chat. Good examples include a Git repository, a client workspace, a research topic, a recurring report, or a documentation workspace. Stay in a normal chat for quick disposable work.

Open Projects from the dashboard, create a project, give it a clear title, and optionally add a Git URL. Write short, concrete project instructions describing what the project is for, how Agent Zero should behave, where files belong, quality rules, and when to ask before acting.

Activate a project from the chat's project picker. When the project name appears in the top bar, that chat uses the project's instructions and workspace. Each chat can use a different project.

Projects can store variables for non-sensitive values and secrets for credentials. Reference secrets by exact name in chat. Keep your own copy of important secrets.

## Model Presets

Source: https://www.agent-zero.ai/p/docs/model-presets/

Model Presets are named shortcuts for model setups. Use them to switch between fast, cheap, local, balanced, and maximum-power setups without rebuilding provider configuration every time.

## Agent Profiles

Source: https://www.agent-zero.ai/p/docs/agent-profiles/

Agent Profiles change the role, instructions, model preset, and capability policy for a chat. Open the profile menu beside the chat input to switch or edit a profile, or use Manage agents to create, duplicate, reset, delete, and set Global or project availability.

Easy mode covers name, preset, instructions, and Tool, MCP, and Skill access. Advanced mode adds identity metadata, individual prompt files, searchable capability policy, and an exact Review plan. On and Off are explicit decisions; Default follows the category's allow-by-default switch.

Manual Global overrides belong under `/a0/usr/agents/<profile-id>/`; project overrides belong under `/a0/usr/projects/<project>/.a0proj/agents/<profile-id>/`. Use YAML for `agent.yaml`, Markdown for prompt files, and JSON for runtime/editor plugin configs. Keep overrides sparse and never edit bundled `/a0/agents` profiles.

A0 CLI exposes `/profile`, `/profile <existing>`, `/profile "<name>" "<instructions>"`, and `/permissions`. Quick creation opens a fresh chat with the new profile selected; the CLI derives Global or project scope from the current chat.

## Skills

Source: https://www.agent-zero.ai/p/docs/skills/

Skills are focused instructions Agent Zero can load when a task needs them. Open a chat, click the plus button in the chat input area, and choose Skills. Click a skill to add it; active skills appear at the top of the selector.

Pin a skill when the chat should keep following the same procedure, such as creating an Agent Profile, reviewing a plugin, following a writing format, or working with a repeated data-cleaning recipe. Keep the active skill list short.

Skills add a specific procedure to the current prompt extras. Agent Profiles change broader role and behavior. Projects add workspace, files, memory, secrets, and project instructions.

## Plugins

Source: https://www.agent-zero.ai/p/docs/plugins/

Plugins extend Agent Zero with Web UI surfaces, tools, settings, scripts, hooks, model providers, and integrations. Open Plugins from the sidebar to manage installed plugins. Use the Plugin Hub to browse and install community plugins.

Put local plugins in `/a0/usr/plugins/<plugin_name>/`. Do not edit root plugin folders for custom work unless intentionally developing Agent Zero itself. If a user-owned plugin has the same ID as a root plugin, the user-owned plugin replaces or extends the root plugin. After adding or changing Web UI extension files, refresh the page so the Web UI extension list is rebuilt.

Install plugins only from trusted sources. Review plugins that run shell commands, install packages, read secrets, or call external services. Store credentials in Secrets or project secrets, not plugin source code.

## Create a Small Plugin

Source: https://www.agent-zero.ai/p/docs/create-plugin/

The first plugin guide uses a tiny local Web UI plugin named `unread_dot`. It has no server endpoint, no tool, no package install, no network calls, and one small visible behavior. Local plugins live under `/a0/usr/plugins/<plugin_name>/`. After creating or changing a Web UI plugin, refresh the page so the extension list is rebuilt.

## Prompts

Source: https://www.agent-zero.ai/p/docs/prompts/

Prompts shape how Agent Zero thinks, speaks, and uses tools. The safest customization path is through a user-owned Agent Profile under `/a0/usr/agents/<profile-name>/prompts/`, not root prompt edits.

Add only the prompt files you want to override. Common files include `agent.system.main.role.md`, `agent.system.main.communication.md`, `agent.system.main.solving.md`, and `agent.system.tool.*.md`. Start with one file; small prompt overrides are easier to debug than a copied prompt tree.

## Subagents

Source: https://www.agent-zero.ai/p/docs/subagents/

Agent Zero can delegate focused parts of a larger problem to subagents. Use delegation when work can be split into independent parts, when one agent should implement and another should review, or when separate research, coding, writing, or verification perspectives help.

Ask for bounded work with a clear finish line. Keep the main chat responsible for final decisions. Avoid asking multiple agents to edit the same files unless coordinating carefully. Active Agent Profiles and Projects can shape subagent behavior.

## Memory

Source: https://www.agent-zero.ai/p/docs/memory/

Memory stores useful context across work. Use the Memory Dashboard to inspect, edit, filter, and clean memories. Project memory can isolate client, repository, or topic-specific context from global memory.

## Task Scheduler

Source: https://www.agent-zero.ai/p/docs/task-scheduler/

The Task Scheduler runs recurring or one-off Agent Zero jobs. Use it for reports, monitoring, timed reminders, maintenance routines, and project-specific automation. Tasks work best when the prompt has a clear finish line and the right project context is attached.

## MCP / A2A

Source: https://www.agent-zero.ai/p/docs/mcp-a2a/

MCP connects external tools and services. A2A connects compatible agent systems. Use these docs when you intentionally need interoperability beyond built-in Agent Zero tools. For basic browsing, start with Agent Zero's built-in Browser before adding external browser MCP tools.

## Secrets

Source: https://www.agent-zero.ai/p/docs/secrets/

Secrets store credentials so agents can use them without exposing values in chat. Agent Zero supports global and project-scoped secrets. Reference secrets by name, keep credentials out of source code, and scope secrets to the smallest workspace that needs them.

## Sharing

Source: https://www.agent-zero.ai/p/docs/sharing/

Sharing covers safe access patterns for teammates, including tunnels, local network access, authentication, and caution around exposing a live agentic environment.

## Updating

Source: https://www.agent-zero.ai/p/docs/updating/

Use Self Update when available. For older installations, back up `usr/` before migration. Manual updates should preserve the old instance until the new one is verified.

## Community and release articles

- Community: https://www.agent-zero.ai/p/docs/community/
- Release articles: https://www.agent-zero.ai/p/articles/tag/releases/