update agent knowledge
Alessandro committed
Feb 10, 2026 at 17:57 UTC
5727f1ade36bd19e6ebdb3a59da2fafd77ad65d0
2 files changed
+816
-449
knowledge/main/about/github_readme.md
+392
-65
@@ -1,65 +1,392 @@
1
-
2
-# Agent Zero Documentation
3
-To begin with Agent Zero, follow the links below for detailed guides on various topics:
4
-
5
-- **[Installation](installation.md):** Set up (or [update](installation.md#how-to-update-agent-zero)) Agent Zero on your system.
6
-- **[Usage Guide](usage.md):** Explore GUI features and usage scenarios.
7
-- **[Architecture Overview](architecture.md):** Understand the internal workings of the framework.
8
-- **[Contributing](contribution.md):** Learn how to contribute to the Agent Zero project.
9
-- **[Troubleshooting and FAQ](troubleshooting.md):** Find answers to common issues and questions.
10
-
11
-### Your experience with Agent Zero starts now!
12
-
13
-- **Download Agent Zero:** Follow the [installation guide](installation.md) to download and run Agent Zero.
14
-- **Join the Community:** Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community to discuss ideas, ask questions, and collaborate with other contributors.
15
-- **Share your Work:** Share your Agent Zero creations, workflows and discoverings on our [Show and Tell](https://github.com/agent0ai/agent-zero/discussions/categories/show-and-tell) area on GitHub.
16
-- **Report Issues:** Use the [GitHub issue tracker](https://github.com/agent0ai/agent-zero/issues) to report framework-relative bugs or suggest new features.
17
-
18
-## Table of Contents
19
-
20
-- [Welcome to the Agent Zero Documentation](#agent-zero-documentation)
21
- - [Your Experience with Agent Zero](#your-experience-with-agent-zero-starts-now)
22
- - [Table of Contents](#table-of-contents)
23
-- [Installation Guide](installation.md)
24
- - [Windows, macOS and Linux Setup](installation.md#windows-macos-and-linux-setup-guide)
25
- - [Settings Configuration](installation.md#settings-configuration)
26
- - [Choosing Your LLMs](installation.md#choosing-your-llms)
27
- - [Installing and Using Ollama](installation.md#installing-and-using-ollama-local-models)
28
- - [Using Agent Zero on Mobile](installation.md#using-agent-zero-on-your-mobile-device)
29
- - [How to Update Agent Zero](installation.md#how-to-update-agent-zero)
30
- - [Full Binaries Installation](installation.md#in-depth-guide-for-full-binaries-installation)
31
-- [Usage Guide](usage.md)
32
- - [Basic Operations](usage.md#basic-operations)
33
- - [Restart Framework](usage.md#restart-framework)
34
- - [Action Buttons](usage.md#action-buttons)
35
- - [File Attachments](usage.md#file-attachments)
36
- - [Tool Usage](usage.md#tool-usage)
37
- - [Example of Tools Usage](usage.md#example-of-tools-usage-web-search-and-code-execution)
38
- - [Multi-Agent Cooperation](usage.md#multi-agent-cooperation)
39
- - [Prompt Engineering](usage.md#prompt-engineering)
40
- - [Voice Interface](usage.md#voice-interface)
41
- - [Mathematical Expressions](usage.md#mathematical-expressions)
42
- - [File Browser](usage.md#file-browser)
43
- - [Backup & Restore](usage.md#backup--restore)
44
-- [Architecture Overview](architecture.md)
45
- - [System Architecture](architecture.md#system-architecture)
46
- - [Runtime Architecture](architecture.md#runtime-architecture)
47
- - [Implementation Details](architecture.md#implementation-details)
48
- - [Core Components](architecture.md#core-components)
49
- - [Agents](architecture.md#1-agents)
50
- - [Tools](architecture.md#2-tools)
51
- - [SearXNG Integration](architecture.md#searxng-integration)
52
- - [Memory System](architecture.md#3-memory-system)
53
- - [Messages History and Summarization](archicture.md#messages-history-and-summarization)
54
- - [Prompts](architecture.md#4-prompts)
55
- - [Knowledge](architecture.md#5-knowledge)
56
- - [Instruments](architecture.md#6-instruments)
57
- - [Extensions](architecture.md#7-extensions)
58
- - [Contributing](contribution.md)
59
- - [Getting Started](contribution.md#getting-started)
60
- - [Making Changes](contribution.md#making-changes)
61
- - [Submitting a Pull Request](contribution.md#submitting-a-pull-request)
62
- - [Documentation Stack](contribution.md#documentation-stack)
63
-- [Troubleshooting and FAQ](troubleshooting.md)
64
- - [Frequently Asked Questions](troubleshooting.md#frequently-asked-questions)
65
- - [Troubleshooting](troubleshooting.md#troubleshooting)
1
+<div align="center">
2
+
3
+# `Agent Zero`
4
+
5
+<p align="center">
6
+ <a href="https://trendshift.io/repositories/11745" target="_blank"><img src="https://trendshift.io/api/badge/repositories/11745" alt="frdel%2Fagent-zero | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
7
+</p>
8
+
9
+[](https://agent-zero.ai) [](https://github.com/sponsors/agent0ai) [](https://x.com/Agent0ai) [](https://discord.gg/B8KZKNsPpj) [](https://www.youtube.com/@AgentZeroFW) [](https://www.linkedin.com/in/jan-tomasek/) [](https://warpcast.com/agent-zero)
10
+
11
+
12
+## Documentation:
13
+
14
+[Introduction](#a-personal-organic-agentic-framework-that-grows-and-learns-with-you) •
15
+[Installation](./docs/setup/installation.md) •
16
+[How to update](./docs/setup/installation.md#how-to-update-agent-zero) <br>
17
+[Development Setup](./docs/setup/dev-setup.md) •
18
+[Usage](./docs/guides/usage.md)
19
+
20
+Or see DeepWiki generated documentation:
21
+
22
+[](https://deepwiki.com/agent0ai/agent-zero)
23
+
24
+</div>
25
+
26
+
27
+<div align="center">
28
+
29
+> ### 🚨 **AGENT ZERO SKILLS** 🚨
30
+> Agent Zero Instruments become **Skills** - portable, structured agent capabilities using the open `SKILL.md` standard (compatible with Claude Code, Codex and more).
31
+>
32
+> **Plus:** Git-based Projects with authentication for public/private repositories - clone codebases directly into isolated workspaces.
33
+>
34
+> See [Usage Guide](./docs/guides/usage.md) and [Projects Tutorial](./docs/guides/projects.md) to get started.
35
+</div>
36
+
37
+
38
+
39
+[](https://youtu.be/lazLNcEYsiQ)
40
+
41
+
42
+## A personal, organic agentic framework that grows and learns with you
43
+
44
+
45
+
46
+- Agent Zero is not a predefined agentic framework. It is designed to be dynamic, organically growing, and learning as you use it.
47
+- Agent Zero is fully transparent, readable, comprehensible, customizable, and interactive.
48
+- Agent Zero uses the computer as a tool to accomplish its (your) tasks.
49
+
50
+# ⚙️ Installation
51
+
52
+Click to open a video to learn how to install Agent Zero:
53
+
54
+[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
55
+
56
+A detailed setup guide for Windows, macOS, and Linux with a video can be found in the Agent Zero Documentation at [this page](./docs/setup/installation.md).
57
+
58
+### ⚡ Quick Start
59
+
60
+```bash
61
+# Pull and run with Docker
62
+
63
+docker pull agent0ai/agent-zero
64
+docker run -p 50001:80 agent0ai/agent-zero
65
+
66
+# Visit http://localhost:50001 to start
67
+```
68
+
69
+
70
+# 💡 Key Features
71
+
72
+1. **General-purpose Assistant**
73
+
74
+- Agent Zero is not pre-programmed for specific tasks (but can be). It is meant to be a general-purpose personal assistant. Give it a task, and it will gather information, execute commands and code, cooperate with other agent instances, and do its best to accomplish it.
75
+- It has a persistent memory, allowing it to memorize previous solutions, code, facts, instructions, etc., to solve tasks faster and more reliably in the future.
76
+
77
+
78
+
79
+2. **Computer as a Tool**
80
+
81
+- Agent Zero uses the operating system as a tool to accomplish its tasks. It has no single-purpose tools pre-programmed. Instead, it can write its own code and use the terminal to create and use its own tools as needed.
82
+- The only default tools in its arsenal are online search, memory features, communication (with the user and other agents), and code/terminal execution. Everything else is created by the agent itself or can be extended by the user.
83
+- Tool usage functionality has been developed from scratch to be the most compatible and reliable, even with very small models.
84
+- **Default Tools:** Agent Zero includes tools like knowledge, code execution, and communication.
85
+- **Creating Custom Tools:** Extend Agent Zero's functionality by creating your own custom tools.
86
+- **Skills (SKILL.md Standard):** Skills are contextual expertise loaded dynamically when relevant. They use the open SKILL.md standard (developed by Anthropic), making them compatible with Claude Code, Cursor, Goose, OpenAI Codex CLI, and GitHub Copilot.
87
+
88
+3. **Multi-agent Cooperation**
89
+
90
+- Every agent has a superior agent giving it tasks and instructions. Every agent then reports back to its superior.
91
+- In the case of the first agent in the chain (Agent 0), the superior is the human user; the agent sees no difference.
92
+- Every agent can create its subordinate agent to help break down and solve subtasks. This helps all agents keep their context clean and focused.
93
+
94
+
95
+
96
+4. **Completely Customizable and Extensible**
97
+
98
+- Almost nothing in this framework is hard-coded. Nothing is hidden. Everything can be extended or changed by the user.
99
+- The whole behavior is defined by a system prompt in the **prompts/default/agent.system.md** file. Change this prompt and change the framework dramatically.
100
+- The framework does not guide or limit the agent in any way. There are no hard-coded rails that agents have to follow.
101
+- Every prompt, every small message template sent to the agent in its communication loop can be found in the **prompts/** folder and changed.
102
+- Every default tool can be found in the **python/tools/** folder and changed or copied to create new predefined tools.
103
+- **Automated configuration** via `A0_SET_` environment variables for deployment automation and easy setup.
104
+
105
+
106
+
107
+5. **Communication is Key**
108
+
109
+- Give your agent a proper system prompt and instructions, and it can do miracles.
110
+- Agents can communicate with their superiors and subordinates, asking questions, giving instructions, and providing guidance. Instruct your agents in the system prompt on how to communicate effectively.
111
+- The terminal interface is real-time streamed and interactive. You can stop and intervene at any point. If you see your agent heading in the wrong direction, just stop and tell it right away.
112
+- There is a lot of freedom in this framework. You can instruct your agents to regularly report back to superiors asking for permission to continue. You can instruct them to use point-scoring systems when deciding when to delegate subtasks. Superiors can double-check subordinates' results and dispute. The possibilities are endless.
113
+
114
+## 🚀 Real-world use cases
115
+
116
+- **Financial Analysis & Charting** - `"Find last month's Bitcoin/USD price trend, correlate with major cryptocurrency news events, generate annotated chart with highlighted key dates"`
117
+
118
+- **Excel Automation Pipeline** - `"Scan incoming directory for financial spreadsheets, validate and clean data, consolidate from multiple sources, generate executive reports with flagged anomalies"`
119
+
120
+- **API Integration Without Code** - `"Use this Google Gemini API snippet to generate product images, remember the integration for future use"` - agent learns and stores the solution in memory
121
+
122
+- **Automated Server Monitoring** - `"Check server status every 30 minutes: CPU usage, disk space, memory. Alert if metrics exceed thresholds"` (scheduled task with project-scoped credentials)
123
+
124
+- **Multi-Client Project Isolation** - Separate projects for each client with isolated memory, custom instructions, and dedicated secrets - prevents context bleed across sensitive work
125
+
126
+## 🐳 Fully Dockerized, with Speech-to-Text and TTS
127
+
128
+
129
+
130
+- Customizable settings allow users to tailor the agent's behavior and responses to their needs.
131
+- The Web UI output is very clean, fluid, colorful, readable, and interactive; nothing is hidden.
132
+- You can load or save chats directly within the Web UI.
133
+- The same output you see in the terminal is automatically saved to an HTML file in **logs/** folder for every session.
134
+
135
+
136
+
137
+- Agent output is streamed in real-time, allowing users to read along and intervene at any time.
138
+- No coding is required; only prompting and communication skills are necessary.
139
+- With a solid system prompt, the framework is reliable even with small models, including precise tool usage.
140
+
141
+## 👀 Keep in Mind
142
+
143
+1. **Agent Zero Can Be Dangerous!**
144
+
145
+- With proper instruction, Agent Zero is capable of many things, even potentially dangerous actions concerning your computer, data, or accounts. Always run Agent Zero in an isolated environment (like Docker) and be careful what you wish for.
146
+
147
+2. **Agent Zero Is Prompt-based.**
148
+
149
+- The whole framework is guided by the **prompts/** folder. Agent guidelines, tool instructions, messages, utility AI functions, it's all there.
150
+
151
+
152
+## 📚 Read the Documentation
153
+
154
+| Page | Description |
155
+|-------|-------------|
156
+| [Installation](./docs/setup/installation.md) | Installation, setup and configuration |
157
+| [Usage](./docs/guides/usage.md) | Basic and advanced usage |
158
+| [Guides](./docs/guides/) | Step-by-step guides: Usage, Projects, API Integration, MCP Setup, A2A Setup |
159
+| [Development Setup](./docs/setup/dev-setup.md) | Development and customization |
160
+| [WebSocket Infrastructure](./docs/developer/websockets.md) | Real-time WebSocket handlers, client APIs, filtering semantics, envelopes |
161
+| [Extensions](./docs/developer/extensions.md) | Extending Agent Zero |
162
+| [Connectivity](./docs/developer/connectivity.md) | External API endpoints, MCP server connections, A2A protocol |
163
+| [Architecture](./docs/developer/architecture.md) | System design and components |
164
+| [Contributing](./docs/guides/contribution.md) | How to contribute |
165
+| [Troubleshooting](./docs/guides/troubleshooting.md) | Common issues and their solutions |
166
+
167
+
168
+## 🎯 Changelog
169
+
170
+### v0.9.8 - Skills, UI Redesign & Git projects
171
+[Release video](https://youtu.be/NV7s78yn6DY)
172
+
173
+- Skills
174
+ - Skills System replacing the legacy Instruments with a new `SKILL.md` standard for structured, portable agent capabilities.
175
+ - Built-in skills, and UI support for importing and listing skills
176
+- Real-time WebSocket infrastructure replacing the polling-based approach for UI state synchronization
177
+- UI Redesign
178
+ - Process groups to visually group agent actions with expand/collapse support
179
+ - Timestamps, steps count and execution time with tool-specific badges
180
+ - Step detail modals with key-value and raw JSON display
181
+ - Collapsible responses with show more/less and copy buttons on code blocks and tables
182
+ - Message queue system allowing users to queue messages while the agent is still processing
183
+ - In-browser file editor for viewing and editing files without leaving the UI
184
+ - Welcome screen redesign with info and warning banners for connection security, missing API keys, and system resources
185
+ - Scheduler redesign with standalone modal, separate task list, detail and editor components, and project support
186
+ - Smooth response rendering and scroll stabilization across chat, terminals, and image viewer
187
+ - Chat width setting and reworked preferences panel
188
+ - Image viewer improvements with scroll support and expanded viewer
189
+ - Redesigned sidebar with reusable dropdown component and streamlined buttons
190
+ - Inline button confirmations for critical actions
191
+ - Improved login design and new logout button
192
+ - File browser enhanced with rename and file actions dropdown
193
+- Git projects
194
+ - Git-based projects with clone authentication for public and private repositories
195
+- Four new LLM providers: CometAPI, Z.AI, Moonshot AI, and AWS Bedrock
196
+- Microsoft Dev Tunnels integration for secure remote access
197
+- User data migration to `/usr` directory for cleaner separation of user and system files
198
+- Subagents system with configurable agent profiles for different roles
199
+- Memory operations offloaded to deferred tasks for better performance
200
+- Environment variables can now configure settings via `A0_SET_*` prefix in `.env`
201
+- Automatic migration with overwrite support for `.env`, scheduler, knowledge, and instruments directories
202
+- Projects support extended to MCP, A2A, and external API
203
+- Workdir outside project support for more flexible file organization
204
+- Agent number tracking in backend and responses for multi-agent identification
205
+- Many bug fixes and stability improvements across the UI, MCP tools, scheduler, uploads, and WebSocket handling
206
+
207
+
208
+### v0.9.7 - Projects
209
+[Release video](https://youtu.be/RrTDp_v9V1c)
210
+- Projects management
211
+ - Support for custom instructions
212
+ - Integration with memory, knowledge, files
213
+ - Project specific secrets
214
+- New Welcome screen/Dashboard
215
+- New Wait tool
216
+- Subordinate agent configuration override support
217
+- Support for multiple documents at once in document_query_tool
218
+- Improved context on interventions
219
+- Openrouter embedding support
220
+- Frontend components refactor and polishing
221
+- SSH metadata output fix
222
+- Support for windows powershell in local TTY utility
223
+- More efficient selective streaming for LLMs
224
+- UI output length limit improvements
225
+
226
+### v0.9.6 - Memory Dashboard
227
+[Release video](https://youtu.be/sizjAq2-d9s)
228
+- Memory Management Dashboard
229
+- Kali update
230
+- Python update + dual installation
231
+- Browser Use update
232
+- New login screen
233
+- LiteLLM retry on temporary errors
234
+- Github Copilot provider support
235
+
236
+### v0.9.5 - Secrets
237
+[Release video](https://www.youtube.com/watch?v=VqxUdt7pjd8)
238
+- Secrets management - agent can use credentials without seeing them
239
+- Agent can copy paste messages and files without rewriting them
240
+- LiteLLM global configuration field
241
+- Custom HTTP headers field for browser agent
242
+- Progressive web app support
243
+- Extra model params support for JSON
244
+- Short IDs for files and memories to prevent LLM errors
245
+- Tunnel component frontend rework
246
+- Fix for timezone change bug
247
+- Notifications z-index fix
248
+
249
+### v0.9.4 - Connectivity, UI
250
+[Release video](https://www.youtube.com/watch?v=C2BAdDOduIc)
251
+- External API endpoints
252
+- Streamable HTTP MCP A0 server
253
+- A2A (Agent to Agent) protocol - server+client
254
+- New notifications system
255
+- New local terminal interface for stability
256
+- Rate limiter integration to models
257
+- Delayed memory recall
258
+- Smarter autoscrolling in UI
259
+- Action buttons in messages
260
+- Multiple API keys support
261
+- Download streaming
262
+- Tunnel URL QR code
263
+- Internal fixes and optimizations
264
+
265
+### v0.9.3 - Subordinates, memory, providers Latest
266
+[Release video](https://www.youtube.com/watch?v=-LfejFWL34k)
267
+- Faster startup/restart
268
+- Subordinate agents can have dedicated prompts, tools and system extensions
269
+- Streamable HTTP MCP server support
270
+- Memory loading enhanced by AI filter
271
+- Memory AI consolidation when saving memories
272
+- Auto memory system configuration in settings
273
+- LLM providers available are set by providers.yaml configuration file
274
+- Venice.ai LLM provider supported
275
+- Initial agent message for user + as example for LLM
276
+- Docker build support for local images
277
+- File browser fix
278
+
279
+### v0.9.2 - Kokoro TTS, Attachments
280
+[Release video](https://www.youtube.com/watch?v=sPot_CAX62I)
281
+
282
+- Kokoro text-to-speech integration
283
+- New message attachments system
284
+- Minor updates: log truncation, hyperlink targets, component examples, api cleanup
285
+
286
+### v0.9.1 - LiteLLM, UI improvements
287
+[Release video](https://youtu.be/crwr0M4Spcg)
288
+- Langchain replaced with LiteLLM
289
+ - Support for reasoning models streaming
290
+ - Support for more providers
291
+ - Openrouter set as default instead of OpenAI
292
+- UI improvements
293
+ - New message grouping system
294
+ - Communication smoother and more efficient
295
+ - Collapsible messages by type
296
+ - Code execution tool output improved
297
+ - Tables and code blocks scrollable
298
+ - More space efficient on mobile
299
+- Streamable HTTP MCP servers support
300
+- LLM API URL added to models config for Azure, local and custom providers
301
+
302
+### v0.9.0 - Agent roles, backup/restore
303
+[Release video](https://www.youtube.com/watch?v=rMIe-TC6H-k)
304
+- subordinate agents can use prompt profiles for different roles
305
+- backup/restore functionality for easier upgrades
306
+- security and bug fixes
307
+
308
+### v0.8.7 - Formatting, Document RAG Latest
309
+[Release video](https://youtu.be/OQJkfofYbus)
310
+- markdown rendering in responses
311
+- live response rendering
312
+- document Q&A tool
313
+
314
+### v0.8.6 - Merge and update
315
+[Release video](https://youtu.be/l0qpK3Wt65A)
316
+- Merge with Hacking Edition
317
+- browser-use upgrade and integration re-work
318
+- tunnel provider switch
319
+
320
+### v0.8.5 - **MCP Server + Client**
321
+[Release video](https://youtu.be/pM5f4Vz3_IQ)
322
+
323
+- Agent Zero can now act as MCP Server
324
+- Agent Zero can use external MCP servers as tools
325
+
326
+### v0.8.4.1 - 2
327
+Default models set to gpt-4.1
328
+- Code execution tool improvements
329
+- Browser agent improvements
330
+- Memory improvements
331
+- Various bugfixes related to context management
332
+- Message formatting improvements
333
+- Scheduler improvements
334
+- New model provider
335
+- Input tool fix
336
+- Compatibility and stability improvements
337
+
338
+### v0.8.4
339
+[Release video](https://youtu.be/QBh_h_D_E24)
340
+
341
+- **Remote access (mobile)**
342
+
343
+### v0.8.3.1
344
+[Release video](https://youtu.be/AGNpQ3_GxFQ)
345
+
346
+- **Automatic embedding**
347
+
348
+### v0.8.3
349
+[Release video](https://youtu.be/bPIZo0poalY)
350
+
351
+- ***Planning and scheduling***
352
+
353
+### v0.8.2
354
+[Release video](https://youtu.be/xMUNynQ9x6Y)
355
+
356
+- **Multitasking in terminal**
357
+- **Chat names**
358
+
359
+### v0.8.1
360
+[Release video](https://youtu.be/quv145buW74)
361
+
362
+- **Browser Agent**
363
+- **UX Improvements**
364
+
365
+### v0.8
366
+[Release video](https://youtu.be/cHDCCSr1YRI)
367
+
368
+- **Docker Runtime**
369
+- **New Messages History and Summarization System**
370
+- **Agent Behavior Change and Management**
371
+- **Text-to-Speech (TTS) and Speech-to-Text (STT)**
372
+- **Settings Page in Web UI**
373
+- **SearXNG Integration Replacing Perplexity + DuckDuckGo**
374
+- **File Browser Functionality**
375
+- **KaTeX Math Visualization Support**
376
+- **In-chat File Attachments**
377
+
378
+### v0.7
379
+[Release video](https://youtu.be/U_Gl0NPalKA)
380
+
381
+- **Automatic Memory**
382
+- **UI Improvements**
383
+- **Instruments**
384
+- **Extensions Framework**
385
+- **Reflection Prompts**
386
+- **Bug Fixes**
387
+
388
+## 🤝 Community and Support
389
+
390
+- [Join our Discord](https://discord.gg/B8KZKNsPpj) for live discussions or [visit our Skool Community](https://www.skool.com/agent-zero).
391
+- [Follow our YouTube channel](https://www.youtube.com/@AgentZeroFW) for hands-on explanations and tutorials
392
+- [Report Issues](https://github.com/agent0ai/agent-zero/issues) for bug fixes and features
knowledge/main/about/installation.md
+424
-384
@@ -1,554 +1,594 @@
1
-# Users installation guide for Windows, macOS and Linux
1
+# Installation Guide
2
3
Click to open a video to learn how to install Agent Zero:
4
5
-[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
5
+[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
6
7
-The following user guide provides instructions for installing and running Agent Zero using Docker, which is the primary runtime environment for the framework. For developers and contributors, we also provide instructions for setting up the [full development environment](#in-depth-guide-for-full-binaries-installation).
7
+## **Goal:** Go from zero to a first working chat with minimal setup.
8
9
10
-## Windows, macOS and Linux Setup Guide
10
+## Step 1: Install Docker Desktop
11
12
+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.
13
13
-1. **Install Docker Desktop:**
14
-- Docker Desktop provides the runtime environment for Agent Zero, ensuring consistent behavior and security across platforms
15
-- The entire framework runs within a Docker container, providing isolation and easy deployment
16
-- Available as a user-friendly GUI application for all major operating systems
14
+**Choose your operating system:**
15
18
-1.1. Go to the download page of Docker Desktop [here](https://www.docker.com/products/docker-desktop/). If the link does not work, just search the web for "docker desktop download".
16
+<table>
17
+<tr>
18
+<td align="center" width="33%">
19
+<a href="#windows-installation">
20
+<img src="../res/setup/oses/windows.png" width="80" alt="Windows"/><br/>
21
+<b>Windows</b>
22
+</a>
23
+</td>
24
+<td align="center" width="33%">
25
+<a href="#macos-installation">
26
+<img src="../res/setup/oses/apple.png" width="80" alt="macOS"/><br/>
27
+<b>macOS</b>
28
+</a>
29
+</td>
30
+<td align="center" width="33%">
31
+<a href="#linux-installation">
32
+<img src="../res/setup/oses/linux.png" width="80" alt="Linux"/><br/>
33
+<b>Linux</b>
34
+</a>
35
+</td>
36
+</tr>
37
+</table>
38
20
-1.2. Download the version for your operating system. For Windows users, the Intel/AMD version is the main download button.
39
+---
40
22
-<img src="res/setup/image-8.png" alt="docker download" width="200"/>
41
+<a name="windows-installation"></a>
42
+## <img src="../res/setup/oses/windows.png" width="30" alt="Windows"/> Windows Installation
43
+
44
+**1.1. Download Docker Desktop**
45
+
46
+Go to the [Docker Desktop download page](https://www.docker.com/products/docker-desktop/) and download the Windows version (Intel/AMD is the main download button).
47
+
48
+<img src="../res/setup/image-8.png" alt="docker download" width="200"/>
49
<br><br>
50
25
-> [!NOTE]
26
-> **Linux Users:** You can install either Docker Desktop or docker-ce (Community Edition).
27
-> For Docker Desktop, follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/).
28
-> For docker-ce, follow the instructions [here](https://docs.docker.com/engine/install/).
29
->
30
-> If you're using docker-ce, you'll need to add your user to the `docker` group:
31
-> ```bash
32
-> sudo usermod -aG docker $USER
33
-> ```
34
-> Log out and back in, then run:
35
-> ```bash
36
-> docker login
37
-> ```
38
-
39
-1.3. Run the installer with default settings. On macOS, drag and drop the application to your Applications folder.
40
-
41
-<img src="res/setup/image-9.png" alt="docker install" width="300"/>
42
-<img src="res/setup/image-10.png" alt="docker install" width="300"/>
43
-
44
-<img src="res/setup/image-12.png" alt="docker install" width="300"/>
51
+**1.2. Run the Installer**
52
+
53
+Run the installer with default settings.
54
+
55
+<img src="../res/setup/image-9.png" alt="docker install" width="300"/>
56
+<img src="../res/setup/image-10.png" alt="docker install" width="300"/>
57
+<br><br>
58
+
59
+**1.3. Launch Docker Desktop**
60
+
61
+Once installed, launch Docker Desktop from your Start menu or desktop shortcut.
62
+
63
+<img src="../res/setup/image-11.png" alt="docker installed" height="100"/>
64
+
65
+✅ **Docker is now installed!**
66
+
67
+### Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero)
68
+
69
+---
70
+
71
+<a name="macos-installation"></a>
72
+## <img src="../res/setup/oses/apple.png" width="30" alt="macOS"/> macOS Installation
73
+
74
+**1.1. Download Docker Desktop**
75
+
76
+Go to the [Docker Desktop download page](https://www.docker.com/products/docker-desktop/) and download the macOS version (choose Apple Silicon or Intel based on your Mac).
77
+
78
+<img src="../res/setup/image-8.png" alt="docker download" width="200"/>
79
<br><br>
80
47
-1.4. Once installed, launch Docker Desktop:
81
+**1.2. Install Docker Desktop**
82
+
83
+Drag and drop the Docker application to your Applications folder.
84
+
85
+<img src="../res/setup/image-12.png" alt="docker install" width="300"/>
86
+<br><br>
87
+
88
+**1.3. Launch Docker Desktop**
89
+
90
+Open Docker Desktop from your Applications folder.
91
49
-<img src="res/setup/image-11.png" alt="docker installed" height="100"/>
50
-<img src="res/setup/image-13.png" alt="docker installed" height="100"/>
92
+<img src="../res/setup/image-13.png" alt="docker installed" height="100"/>
93
<br><br>
94
53
-> [!IMPORTANT]
54
-> **macOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings →
55
-> Advanced, enable "Allow the default Docker socket to be used (requires password)."
95
+**1.4. Configure Docker Socket**
96
+
97
+> [!NOTE]
98
+> **Important macOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings → Advanced, enable "Allow the default Docker socket to be used (requires password)."
99
+
100
+
101
+
102
+✅ **Docker is now installed!**
103
+
104
+### Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero)
105
+
106
+---
107
+
108
+<a name="linux-installation"></a>
109
+## <img src="../res/setup/oses/linux.png" width="30" alt="Linux"/> Linux Installation
110
+
111
+**1.1. Choose Installation Method**
112
+
113
+You can install either Docker Desktop or docker-ce (Community Edition).
114
+
115
+**Option A: Docker Desktop (Recommended for beginners)**
116
+
117
+Follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/).
118
+
119
+**Option B: docker-ce (Lightweight alternative)**
120
+
121
+Follow the installation instructions [here](https://docs.docker.com/engine/install/).
122
+
123
+**1.2. Post-Installation Steps (docker-ce only)**
124
+
125
+If you installed docker-ce, add your user to the `docker` group:
126
+
127
+```bash
128
+sudo usermod -aG docker $USER
129
+```
130
+
131
+Log out and back in, then authenticate:
132
+
133
+```bash
134
+docker login
135
+```
136
+
137
+**1.3. Launch Docker**
138
+
139
+If you installed Docker Desktop, launch it from your applications menu.
140
+
141
+✅ **Docker is now installed!**
142
+
143
+> [!TIP]
144
+> **Deploying on a VPS/Server?** For production deployments with reverse proxy, SSL, and domain configuration, see the [VPS Deployment Guide](vps-deployment.md).
145
+
146
+---
147
57
-
148
+## Step 2: Run Agent Zero
149
59
-2. **Run Agent Zero:**
150
+### 2.1. Pull the Agent Zero Docker Image
151
61
-- Note: Agent Zero also offers a Hacking Edition based on Kali linux with modified prompts for cybersecurity tasks. The setup is the same as the regular version, just use the agent0ai/agent-zero:hacking image instead of agent0ai/agent-zero.
152
+**Using Docker Desktop GUI:**
153
63
-2.1. Pull the Agent Zero Docker image:
154
- Search for `agent0ai/agent-zero` in Docker Desktop
155
- Click the `Pull` button
156
- The image will be downloaded to your machine in a few minutes
157
68
-
158
+
159
70
-> [!TIP]
71
-> Alternatively, run the following command in your terminal:
72
->
73
-> ```bash
74
-> docker pull agent0ai/agent-zero
75
-> ```
76
-
77
-2.2. Create a data directory for persistence:
78
-- Choose or create a directory on your machine where you want to store Agent Zero's data
79
-- This can be any location you prefer (e.g., `C:/agent-zero-data` or `/home/user/agent-zero-data`)
80
-- This directory will contain all your Agent Zero files, like the legacy root folder structure:
81
- - `/memory` - Agent's memory and learned information
82
- - `/knowledge` - Knowledge base
83
- - `/instruments` - Instruments and functions
84
- - `/prompts` - Prompt files
85
- - `/work_dir` - Working directory
86
- - `.env` - Your API keys
87
- - `settings.json` - Your Agent Zero settings
160
+**Using Terminal:**
161
+
162
+```bash
163
+docker pull agent0ai/agent-zero
164
+```
165
+
166
+### 2.2. (Optional) Map Folders for Persistence
167
+
168
+Choose or create a folder on your computer where Agent Zero will save its data.
169
+
170
+### Setting up persistence is needed only if you want your data and files to remain available even after you delete the container.
171
+
172
+You can pick any location you find convenient:
173
+
174
+- **Windows:** `C:\agent-zero-data`
175
+- **macOS/Linux:** `/home/user/agent-zero-data`
176
+
177
+You can map just the `/a0/usr` directory (recommended) or individual subfolders of `/a0` to a local directory.
178
+
179
+> [!CAUTION]
180
+> Do **not** map the entire `/a0` directory: it contains the application code and can break upgrades.
181
182
> [!TIP]
90
-> Choose a location that's easy to access and backup. All your Agent Zero data
91
-> will be directly accessible in this directory.
183
+> Choose a location that's easy to access and backup. All your Agent Zero data will be directly accessible in this directory.
184
+
185
+### 2.3. Run the Container
186
+
187
+**Using Docker Desktop GUI:**
188
93
-2.3. Run the container:
94
-- In Docker Desktop, go back to the "Images" tab
189
+- In Docker Desktop, go to the "Images" tab
190
- Click the `Run` button next to the `agent0ai/agent-zero` image
191
- Open the "Optional settings" menu
97
-- Set the port to `0` in the second "Host port" field (for automatic port assignment)
192
+- **Ensure at least one host port is mapped to container port `80`** (set host port to `0` for automatic assignment)
193
+- Click the `Run` button
194
99
-Optionally you can map local folders for file persistence:
100
-- Under "Volumes", configure:
101
- - Host path: Your chosen directory (e.g., `C:\agent-zero-data`)
102
- - Container path: `/a0`
195
+
196
+
197
104
-
198
+The container will start and show in the "Containers" tab:
199
106
-- Click the `Run` button in the "Images" tab.
107
-- The container will start and show in the "Containers" tab
200
+
201
109
-
110
-
111
-> [!TIP]
112
-> Alternatively, run the following command in your terminal:
113
-> ```bash
114
-> docker run -p $PORT:80 -v /path/to/your/data:/a0 agent0ai/agent-zero
115
-> ```
116
-> - Replace `$PORT` with the port you want to use (e.g., `50080`)
117
-> - Replace `/path/to/your/data` with your chosen directory path
202
+### 2.4. Access the Web UI
203
119
-2.4. Access the Web UI:
120
-- The framework will take a few seconds to initialize and the Docker logs will look like the image below.
121
-- Find the mapped port in Docker Desktop (shown as `<PORT>:80`) or click the port right under the container ID as shown in the image below
204
+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:
205
123
-
206
+
207
125
-- Open `http://localhost:<PORT>` in your browser
126
-- The Web UI will open. Agent Zero is ready for configuration!
208
+Open `http://localhost:<PORT>` in your browser. The Web UI will open - Agent Zero is ready for configuration!
209
128
-
210
+
211
212
> [!TIP]
131
-> You can also access the Web UI by clicking the ports right under the container ID in Docker Desktop.
213
+> You can also access the Web UI by clicking the port link directly under the container ID in Docker Desktop.
214
215
> [!NOTE]
134
-> After starting the container, you'll find all Agent Zero files in your chosen
135
-> directory. You can access and edit these files directly on your machine, and
136
-> the changes will be immediately reflected in the running container.
216
+> After starting the container, you'll find all Agent Zero files in your chosen directory. You can access and edit these files directly on your machine, and the changes will be immediately reflected in the running container.
217
138
-3. Configure Agent Zero
139
-- Refer to the following sections for a full guide on how to configure Agent Zero.
218
+**Running A0 using Terminal?**
219
141
-## Settings Configuration
142
-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.
220
+```bash
221
+docker run -p 0:80 -v /path/to/your/work_dir:/a0/usr agent0ai/agent-zero
222
+```
223
+
224
+- Replace `0` with a fixed port if you prefer (e.g., `50080:80`)
225
+
226
+---
227
+
228
+## Step 3: Configure Agent Zero
229
+
230
+The UI will show a warning banner "Missing LLM API Key for current settings". Click on `Add your API key` to enter Settings and start configuring A0.
231
+
232
+### Settings Configuration
233
+
234
+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.
235
236
### Agent Configuration
145
-- **Prompts Subdirectory:** Choose the subdirectory within `/prompts` for agent behavior customization. The 'default' directory contains the standard prompts.
237
+
238
+- **Agent Profile:** Select the agent profile (e.g., `agent0`, `hacker`, `researcher`). Profiles can override prompts, tools, and extensions.
239
- **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances.
240
- **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding.
241
149
-
242
+> [!NOTE]
243
+> Since v0.9.7, custom prompts belong in `/a0/agents/<agent_name>/prompts/` rather than a shared `/prompts` folder. See the [Extensions guide](../developer/extensions.md#prompts) for details.
244
+
245
+> [!NOTE]
246
+> The Hacker profile is included in the main image. After launch, choose the **hacker** agent profile in Settings if you want the security-focused prompts and tooling. The "hacker" branch is deprecated.
247
+
248
+
249
250
### Chat Model Settings
152
-- **Provider:** Select the chat model provider (e.g., Ollama)
153
-- **Model Name:** Choose the specific model (e.g., llama3.2)
154
-- **Temperature:** Adjust response randomness (0 for deterministic, higher values for more creative responses)
251
+
252
+- **Provider:** Select the chat model provider (e.g., Anthropic)
253
+- **Model Name:** Choose the specific model (e.g., claude-sonnet-4-5)
254
- **Context Length:** Set the maximum token limit for context window
255
- **Context Window Space:** Configure how much of the context window is dedicated to chat history
256
158
-
257
+
258
+
259
+**Model naming is provider-specific.**
260
+
261
+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 "<name-of-ai-model> model naming".
262
+
263
+> [!TIP]
264
+> **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.
265
+
266
+> [!TIP]
267
+> **API URL:** URL of the API endpoint for the chat model - only needed for some providers like Ollama, LM Studio, Azure, etc.
268
269
### Utility Model Configuration
161
-- **Provider & Model:** Select a smaller, faster model for utility tasks like memory organization and summarization
270
+
271
+- **Provider & Model:** Select a model for utility tasks like memory organization and summarization
272
- **Temperature:** Adjust the determinism of utility responses
273
164
-### Embedding Model Settings
274
+> [!NOTE]
275
+> Utility models need to be strong enough to extract and consolidate memory reliably. Very small models (e.g., 4B) often fail at this; 70B-class models or high-quality cloud "flash/mini" models work best.
276
+
277
+### Embedding Model Settings [Optional]
278
+
279
- **Provider:** Choose the embedding model provider (e.g., OpenAI)
280
- **Model Name:** Select the specific embedding model (e.g., text-embedding-3-small)
281
282
+> [!NOTE]
283
+> 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.
284
+
285
### Speech to Text Options
286
+
287
- **Model Size:** Choose the speech recognition model size
288
- **Language Code:** Set the primary language for voice recognition
289
- **Silence Settings:** Configure silence threshold, duration, and timeout parameters for voice input
290
291
### API Keys
174
-- Configure API keys for various service providers directly within the Web UI
175
-- Click `Save` to confirm your settings
292
+
293
+Configure API keys for various service providers directly within the Web UI. Click `Save` to confirm your settings.
294
+
295
+> [!NOTE]
296
+> **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.
297
+
298
+> [!TIP]
299
+> 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.
300
+
301
+> [!CAUTION]
302
+> **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.
303
304
### Authentication
305
+
306
- **UI Login:** Set username for web interface access
307
- **UI Password:** Configure password for web interface security
308
- **Root Password:** Manage Docker container root password for SSH access
309
182
-
310
+
311
312
### Development Settings
185
-- **RFC Parameters (local instances only):** configure URLs and ports for remote function calls between instances
313
+
314
+- **RFC Parameters (local instances only):** Configure URLs and ports for remote function calls between instances
315
- **RFC Password:** Configure password for remote function calls
187
-Learn more about Remote Function Calls and their purpose [here](#7-configure-agent-zero-rfc).
316
+
317
+Learn more about Remote Function Calls in the [Development Setup guide](dev-setup.md#step-6-configure-ssh-and-rfc-connection).
318
319
> [!IMPORTANT]
320
> Always keep your API keys and passwords secure.
321
192
-# Choosing Your LLMs
193
-The Settings page is the control center for selecting the Large Language Models (LLMs) that power Agent Zero. You can choose different LLMs for different roles:
322
+> [!NOTE]
323
+> On Windows host installs (non-Docker), you must use RFC to run shell code on the host system. The Docker runtime handles this automatically.
324
+
325
+---
326
+
327
+## Choosing Your LLMs
328
+
329
+The Settings page is the control center for selecting the Large Language Models (LLMs) that power Agent Zero. You can choose different LLMs for different roles:
330
331
| LLM Role | Description |
332
| --- | --- |
333
| `chat_llm` | This is the primary LLM used for conversations and generating responses. |
198
-| `utility_llm` | This LLM handles internal tasks like summarizing messages, managing memory, and processing internal prompts. Using a smaller, less expensive model here can improve efficiency. |
199
-| `embedding_llm` | This LLM is responsible for generating embeddings used for memory retrieval and knowledge base lookups. Changing the `embedding_llm` will re-index all of A0's memory. |
334
+| `utility_llm` | This LLM handles internal tasks like summarizing messages, managing memory, and processing internal prompts. Using a smaller, less expensive model here can improve efficiency. |
335
+| `browser_llm` | This LLM powers the browser agent for web navigation and interaction tasks. Vision support is recommended for better page understanding. |
336
+| `embedding_llm` | The embedding model shipped with A0 runs on CPU and is responsible for generating embeddings used for memory retrieval and knowledge base lookups. Changing the `embedding_llm` will re-index all of A0's memory. |
337
338
**How to Change:**
339
+
340
1. Open Settings page in the Web UI.
203
-2. Choose the provider for the LLM for each role (Chat model, Utility model, Embedding model) and write the model name.
341
+2. Choose the provider for the LLM for each role (Chat model, Utility model, Browser model, Embedding model) and write the model name.
342
3. Click "Save" to apply the changes.
343
206
-## Important Considerations
344
+### Important Considerations
345
208
-> [!CAUTION]
209
-> Changing the `embedding_llm` will re-index all the memory and knowledge, and
210
-> requires clearing the `memory` folder to avoid errors, as the embeddings can't be
211
-> mixed in the vector database. Note that this will DELETE ALL of Agent Zero's memory.
346
+#### Model Naming by Provider
347
+
348
+Use the naming format required by your selected provider:
349
+
350
+| Provider | Model Name Format | Example |
351
+| --- | --- | --- |
352
+| OpenAI | Model name only | `claude-sonnet-4-5` |
353
+| OpenRouter | Provider prefix mostly required | `anthropic/claude-sonnet-4-5` |
354
+| Ollama | Model name only | `gpt-oss:20b` |
355
+
356
+> [!TIP]
357
+> If you see "Invalid model ID," verify the provider and naming format on the provider website, or search the web for "<name-of-ai-model> model naming".
358
+
359
+#### Context Window & Memory Split
360
+
361
+- Set the **total context window** (e.g., 100k) first.
362
+- Then tune the **chat history portion** as a fraction of that total.
363
+- Extremely large totals can make even small fractions very large; adjust thoughtfully.
364
+
365
+#### Utility Model Guidance
366
+
367
+- Utility models handle summarization and memory extraction.
368
+- Very small models (≈4B) usually fail at reliable context extraction.
369
+- Aim for ~70B class models or strong cloud "flash/mini" models for better results.
370
+
371
+#### Reasoning/Thinking Models
372
+
373
+- Reasoning can increase cost and latency. Some models perform better **without** reasoning.
374
+- If a model supports it, disable reasoning via provider-specific parameters (e.g., Venice `disable_thinking=true`).
375
+
376
+---
377
378
## Installing and Using Ollama (Local Models)
214
-If you're interested in Ollama, which is a powerful tool that allows you to run various large language models locally, here's how to install and use it:
379
216
-#### First step: installation
217
-**On Windows:**
380
+Ollama is a powerful tool that allows you to run various large language models locally.
381
+
382
+---
383
219
-Download Ollama from the official website and install it on your machine.
384
+<a name="windows-ollama-installation"></a>
385
+### <img src="../res/setup/oses/windows.png" width="30" alt="Windows"/> Windows Ollama Installation
386
+
387
+Download and install Ollama from the official website:
388
389
<button>[Download Ollama Setup](https://ollama.com/download/OllamaSetup.exe)</button>
390
223
-**On macOS:**
224
-```
225
-brew install ollama
226
-```
227
-Otherwise choose macOS installer from the [official website](https://ollama.com/).
391
+Once installed, continue to [Pulling Models](#pulling-models).
392
229
-**On Linux:**
230
-```bash
231
-curl -fsSL https://ollama.com/install.sh | sh
232
-```
393
+---
394
234
-**Finding Model Names:**
235
-Visit the [Ollama model library](https://ollama.com/library) for a list of available models and their corresponding names. The format is usually `provider/model-name` (or just `model-name` in some cases).
395
+<a name="macos-ollama-installation"></a>
396
+### <img src="../res/setup/oses/apple.png" width="30" alt="macOS"/> macOS Ollama Installation
397
237
-#### Second step: pulling the model
238
-**On Windows, macOS, and Linux:**
239
-```
240
-ollama pull <model-name>
398
+**Using Homebrew:**
399
+
400
+```bash
401
+brew install ollama
402
```
403
243
-1. Replace `<model-name>` with the name of the model you want to use. For example, to pull the Mistral Large model, you would use the command `ollama pull mistral-large`.
404
+**Using Installer:**
405
245
-2. A CLI message should confirm the model download on your system
406
+Download from the [official website](https://ollama.com/).
407
247
-#### Selecting your model within Agent Zero
248
-1. Once you've downloaded your model(s), you must select it in the Settings page of the GUI.
408
+Once installed, continue to [Pulling Models](#pulling-models).
409
250
-2. Within the Chat model, Utility model, or Embedding model section, choose Ollama as provider.
410
+---
411
252
-3. Write your model code as expected by Ollama, in the format `llama3.2` or `qwen2.5:7b`
412
+<a name="linux-ollama-installation"></a>
413
+### <img src="../res/setup/oses/linux.png" width="30" alt="Linux"/> Linux Ollama Installation
414
254
-4. Click `Save` to confirm your settings.
415
+Run the installation script:
416
256
-
417
+```bash
418
+curl -fsSL https://ollama.com/install.sh | sh
419
+```
420
258
-#### Managing your downloaded models
259
-Once you've downloaded some models, you might want to check which ones you have available or remove any you no longer need.
421
+Once installed, continue to [Pulling Models](#pulling-models).
422
261
-- **Listing downloaded models:**
262
- To see a list of all the models you've downloaded, use the command:
263
- ```
264
- ollama list
265
- ```
266
-- **Removing a model:**
267
- If you need to remove a downloaded model, you can use the `ollama rm` command followed by the model name:
268
- ```
269
- ollama rm <model-name>
270
- ```
423
+---
424
425
+### Pulling Models
426
273
-- 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.
427
+**Finding Model Names:**
428
275
-## Using Agent Zero on your mobile device
276
-Agent Zero's Web UI is accessible from any device on your network through the Docker container:
429
+Visit the [Ollama model library](https://ollama.com/library) for a list of available models and their corresponding names. Ollama models are referenced by **model name only** (for example, `llama3.2`).
430
278
-1. The Docker container automatically exposes the Web UI on all network interfaces
279
-2. Find the mapped port in Docker Desktop:
280
- - Look under the container name (usually in the format `<PORT>:80`)
281
- - For example, if you see `32771:80`, your port is `32771`
282
-3. Access the Web UI from any device using:
283
- - Local access: `http://localhost:<PORT>`
284
- - Network access: `http://<YOUR_COMPUTER_IP>:<PORT>`
431
+**Pull a model:**
432
286
-> [!TIP]
287
-> - Your computer's IP address is usually in the format `192.168.x.x` or `10.0.x.x`
288
-> - You can find your external IP address by running `ipconfig` (Windows) or `ifconfig` (Linux/Mac)
289
-> - The port is automatically assigned by Docker unless you specify one
433
+```bash
434
+ollama pull <model-name>
435
+```
436
291
-> [!NOTE]
292
-> If you're running Agent Zero directly on your system (legacy approach) instead of
293
-> using Docker, you'll need to configure the host manually in `run_ui.py` to run on all interfaces using `host="0.0.0.0"`.
437
+Replace `<model-name>` with the name of the model you want to use. For example: `ollama pull mistral-large`
438
295
-For developers or users who need to run Agent Zero directly on their system,see the [In-Depth Guide for Full Binaries Installation](#in-depth-guide-for-full-binaries-installation).
439
+### Configuring Ollama in Agent Zero
440
297
-# How to update Agent Zero
441
+1. Once you've downloaded your model(s), select it in the Settings page of the GUI.
442
+2. Within the Chat model, Utility model, or Embedding model section, choose **Ollama** as provider.
443
+3. Write your model code as expected by Ollama, in the format `llama3.2` or `qwen2.5:7b`
444
+4. Provide your API base URL to your Ollama API endpoint, usually `http://host.docker.internal:11434`
445
+5. Click `Save` to confirm your settings.
446
299
-1. **If you come from the previous version of Agent Zero:**
300
-- Your data is safely stored across various directories and files inside the Agent Zero folder.
301
-- To update to the new Docker runtime version, you might want to backup the following files and directories:
302
- - `/memory` - Agent's memory
303
- - `/knowledge` - Custom knowledge base (if you imported any custom knowledge files)
304
- - `/instruments` - Custom instruments and functions (if you created any custom)
305
- - `/usr/settings.json` - Your Agent Zero settings
306
- - `/usr/chats/` - Your chat history
307
-- Once you have saved these files and directories, you can proceed with the Docker runtime [installation instructions above](#windows-macos-and-linux-setup-guide) setup guide.
308
-- Reach for the folder where you saved your data and copy it to the new Agent Zero folder set during the installation process.
309
-- Agent Zero will automatically detect your saved data and use it across memory, knowledge, instruments, prompts and settings.
447
+
448
311
-> [!IMPORTANT]
312
-> If you have issues loading your settings, you can try to delete the `/usr/settings.json` file and let Agent Zero generate a new one.
313
-> The same goes for chats in `/usr/chats/`, they might be incompatible with the new version
449
+> [!NOTE]
450
+> If Agent Zero runs in Docker and Ollama runs on the host, ensure port **11434** is reachable from the container. If both services are in the same Docker network, you can use `http://<container_name>:11434` instead of `host.docker.internal`.
451
315
-2. **Update Process (Docker Desktop)**
316
-- Go to Docker Desktop and stop the container from the "Containers" tab
317
-- Right-click and select "Remove" to remove the container
318
-- Go to "Images" tab and remove the `agent0ai/agent-zero` image or click the three dots to pull the difference and update the Docker image.
452
+### Managing Downloaded Models
453
320
-
454
+**Listing downloaded models:**
455
322
-- Search and pull the new image if you chose to remove it
323
-- Run the new container with the same volume settings as the old one
456
+```bash
457
+ollama list
458
+```
459
325
-> [!IMPORTANT]
326
-> Make sure to use the same volume mount path when running the new
327
-> container to preserve your data. The exact path depends on where you stored
328
-> your Agent Zero data directory (the chosen directory on your machine).
460
+**Removing a model:**
461
+
462
+```bash
463
+ollama rm <model-name>
464
+```
465
466
> [!TIP]
331
-> Alternatively, run the following commands in your terminal:
332
->
333
-> ```bash
334
-> # Stop the current container
335
-> docker stop agent-zero
336
->
337
-> # Remove the container (data is safe in the folder)
338
-> docker rm agent-zero
339
->
340
-> # Remove the old image
341
-> docker rmi agent0ai/agent-zero
342
->
343
-> # Pull the latest image
344
-> docker pull agent0ai/agent-zero
345
->
346
-> # Run new container with the same volume mount
347
-> docker run -p $PORT:80 -v /path/to/your/data:/a0 agent0ai/agent-zero
348
-> ```
349
-
350
-3. **Full Binaries**
351
-- Using Git/GitHub: Pull the latest version of the Agent Zero repository.
352
-- The custom knowledge, solutions, memory, and other data will get ignored, so you don't need to worry about losing any of your custom data. The same goes for your .env file with all of your API keys and settings.json.
353
-
354
-> [!WARNING]
355
-> - If you update manually, beware: save your .env file with the API keys, and look for new dependencies in requirements.txt.
356
-> - If any changes are made to the requirements of the updated version, you have to execute this command inside the a0 conda env after activating it:
357
-> ```bash
358
-> pip install -r requirements.txt
359
-
360
-# In-Depth Guide for Full Binaries Installation
361
-- Agent Zero is a framework. It's made to be customized, edited, enhanced. Therefore you need to install the necessary components to run it when downloading its full binaries. This guide will help you to do so.
362
-- The following step by step instructions can be followed along with a video for this tutorial on how to make Agent Zero work with its full development environment.
363
-
364
-[](https://youtu.be/8H7mFsvxKYQ)
365
-
366
-## Reminders:
367
-1. There's no need to install Python, Conda will manage that for you.
368
-2. You don't necessarily need API keys: Agent Zero can run with local models. For this tutorial though, we will leave it to the default OpenAI API. A guide for downloading Ollama along with local models is available [here](#installing-and-using-ollama-local-models).
369
-3. Visual Studio Code or any other code editor is not mandatory, but it makes it easier to navigate and edit files.
370
-4. Git/GitHub is not mandatory, you can download the framework files through your browser. We will not be showing how to use Git in this tutorial.
371
-5. Docker is not mandatory for the full binaries installation, since the framework will run on your machine connecting to the Docker container through the Web UI RFC functionality.
372
-6. Running Agent Zero without Docker makes the process more complicated and it's thought for developers and contributors.
373
-
374
-> [!IMPORTANT]
375
-> Linux instructions are provided as general instructions for any Linux distribution. If you're using a distribution other than Debian/Ubuntu, you may need to adjust the instructions accordingly.
376
->
377
-> For Debian/Ubuntu, just follow the macOS instructions, as they are the same.
378
-
379
-## 1. Install Conda (miniconda)
380
-- Conda is a Python environment manager, it will help you keep your projects and installations separated.
381
-- It's a lightweight version of Anaconda that includes only conda, Python, the packages they depend on, and a small number of other useful packages, including pip, zlib and a few others.
382
-
383
-1. Go to the download page of miniconda [here](https://docs.anaconda.com/miniconda/#miniconda-latest-installer-links). If the link does not work, just search the web for "miniconda download".
384
-2. Based on your operating system, download the right installer of miniconda. For macOS select the version with "pkg" at the end.
385
-
386
-<img src="res/setup/image-1.png" alt="miniconda download win" width="500"/>
387
-<img src="res/setup/image-5.png" alt="miniconda download macos" width="500"/>
388
-<br><br>
467
+> 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.
468
390
-3. Run the installer and go through the installation process, here you can leave everything to default and just click Next, Next... The same goes for macOS with the "pkg" graphical installer.
469
+---
470
392
-<img src="res/setup/image.png" alt="miniconda install" width="200"/>
393
-<img src="res/setup/image-2.png" alt="miniconda install" width="200"/>
394
-<img src="res/setup/image-3.png" alt="miniconda install" width="200"/>
395
-<img src="res/setup/image-4.png" alt="miniconda install" width="200"/>
396
-<br><br>
471
+## How to Update Agent Zero
472
398
-4. After the installation is complete, you should have "Anaconda Powershell Prompt" installed on your Windows machine. On macOS, when you open the Terminal application in your Applications folder and type "conda --version", you should see the version installed.
473
+> [!NOTE]
474
+> Since v0.9, Agent Zero includes a Backup & Restore workflow in the Settings UI. This is the **safest** way to upgrade Docker instances.
475
400
-<img src="res/setup/image-6.png" alt="miniconda installed" height="100"/>
401
-<img src="res/setup/image-7.png" alt="miniconda installed" height="100"/>
402
-<br><br>
476
+### Recommended Update Process (Docker)
477
478
+1. **Keep the old container running** and note its port.
479
+2. **Pull the new image** (`agent0ai/agent-zero:latest`).
480
+3. **Start a new container** on a different host port.
481
+4. In the **old** instance, open **Settings → Backup & Restore** and create a backup.
482
+5. In the **new** instance, restore that backup from the same panel.
483
405
-## 2. Download Agent Zero
406
-- You can clone the Agent Zero repository (https://github.com/agent0ai/agent-zero) from GitHub if you know how to use Git. In this tutorial I will just show how to download the files.
484
+> [!TIP]
485
+> If the new instance fails to load settings, remove `/a0/usr/settings.json` and restart to regenerate default settings.
486
408
-1. Go to the Agent Zero releases [here](https://github.com/agent0ai/agent-zero/releases).
409
-2. The latest release is on the top of the list, click the "Source Code (zip)" button under "Assets" to download it.
487
+---
488
411
-<img src="res/setup/image-14-u.png" alt="agent zero download" width="500"/>
412
-<br><br>
489
+## Using Agent Zero on Your Mobile Device
490
414
-3. Extract the downloaded archive where you want to have it. I will extract them to "agent-zero" folder on my Desktop - "C:\Users\frdel\Desktop\agent-zero" on Windows and "/Users/frdel/Desktop/agent-zero" on macOS.
491
+Agent Zero can be accessed from mobile devices and other computers using the built-in **Tunnel feature**.
492
416
-## 3. Set up Conda environment
417
-- Now that we have the project files and Conda, we can create **virtual Python environment** for this project, activate it and install requirements.
493
+### Recommended: Using Tunnel (Remote Access)
494
419
-1. Open your **"Anaconda Powershell Prompt"** application on windows or **"Terminal"** application on macOS.
420
-2. In the terminal, navigate to your Agent Zero folder using **"cd"** command. Replace the path with your actual Agent Zero folder path.
421
-~~~
422
-cd C:\Users\frdel\Desktop\agent-zero
423
-~~~
424
-You should see your folder has changed on the next terminal line.
495
+The Tunnel feature allows secure access to your Agent Zero instance from anywhere:
496
426
-<img src="res/setup/image-15.png" alt="agent zero cd" height="100"/>
427
-<img src="res/setup/image-16.png" alt="agent zero cd" height="100"/>
428
-<br><br>
497
+1. Open Settings in the Web UI
498
+2. Navigate to the **External Services** tab
499
+3. Click on **Flare Tunnel** in the navigation menu
500
+4. Click **Create Tunnel** to generate a secure HTTPS URL
501
+5. Share this URL to access Agent Zero from any device
502
430
-3. Create Conda environment using command **"conda create"**. After **"-n"** is your environment name, you can choose your own, i will use **"a0"** - short for Agent Zero. After **"python"** is the Python version that Conda will install for you into this environment, right now, 3.12 works fine. **-y** skips confirmations.
431
-~~~
432
-conda create -n a0 python=3.12 -y
433
-~~~
503
+> [!IMPORTANT]
504
+> **Security:** Always set a username and password in Settings → Authentication before creating a tunnel to secure your instance on the internet.
505
435
-4. Once done, activate the new environment for this terminal window by another command:
436
-~~~
437
-conda activate a0
438
-~~~
439
-And you should see that the **(base)** on the left has changed to **(a0)**. This means that this terminal now uses the new **a0** virtual environment and all packages will be installed into this environment.
506
+For complete details on tunnel configuration and security considerations, see the [Remote Access via Tunneling](../guides/usage.md#remote-access-via-tunneling) section in the Usage Guide.
507
441
-<img src="res/setup/image-17.png" alt="conda env" height="200"/>
442
-<img src="res/setup/image-18.png" alt="conda env" height="200"/>
443
-<br><br>
508
+### Alternative: Local Network Access
509
445
-> [!IMPORTANT]
446
-> If you open a new terminal window, you will need to activate the environment with
447
-> "conda activate a0" again for that window.
510
+If you prefer to keep access limited to your local network:
511
449
-5. Install requirements using **"pip"**. Pip is a Python package manager. We can install all required packages from requirements.txt file using command:
450
-~~~
451
-pip install -r requirements.txt
452
-~~~
453
-This might take some time. If you get any errors regarding version conflicts and compatibility, double check that your environment is activated and that you created that environment with the correct Python version.
512
+1. Find the mapped port in Docker Desktop (format: `<PORT>:80`, e.g., `32771:80`)
513
+2. Access from the same computer: `http://localhost:<PORT>`
514
+3. Access from other devices on the network: `http://<YOUR_COMPUTER_IP>:<PORT>`
515
455
-<img src="res/setup/image-19.png" alt="conda reqs" height="200"/>
456
-<br><br>
516
+> [!TIP]
517
+> 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`.
518
458
-## 4. Install Docker (Docker Desktop application)
459
-Simply put, Docker is a way of running virtual computers on your machine. These are lightweight, disposable and isolated from your operating system, so it is a way to sandbox Agent Zero.
460
-- Agent Zero only connects to the Docker container when it needs to execute code and commands. The frameworks itself runs on your machine.
461
-- Docker has a desktop application with GUI for all major operating system, which is the recommended way to install it.
519
+For developers or users who need to run Agent Zero directly on their system, see the [In-Depth Guide for Full Binaries Installation](dev-setup.md).
520
463
-1. Go to the download page of Docker Desktop [here](https://www.docker.com/products/docker-desktop/). If the link does not work, just search the web for "docker desktop download".
464
-2. Download the version for your operating system. Don't be tricked by the seemingly missing windows intel/amd version, it's the button itself, not in the dropdown menu.
521
+---
522
466
-<img src="res/setup/image-8.png" alt="docker download" width="200"/>
467
-<br><br>
523
+## Advanced: Automated Configuration via Environment Variables
524
469
-3. Run the installer and go through the installation process. It should be even shorter than Conda installation, you can leave everything to default. On macOS, the installer is a "dmg" image, so just drag and drop the application to your Applications folder like always.
525
+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.
526
471
-<img src="res/setup/image-9.png" alt="docker install" width="300"/>
472
-<img src="res/setup/image-10.png" alt="docker install" width="300"/>
527
+**Usage:**
528
474
-<img src="res/setup/image-12.png" alt="docker install" width="300"/>
475
-<br><br>
529
+Add variables to your `.env` file in the format:
530
531
+```env
532
+A0_SET_{setting_name}={value}
533
+```
534
478
-4. Once installed, you should see Docker Desktop application on your Windows/Mac machine.
535
+**Examples:**
536
480
-<img src="res/setup/image-11.png" alt="docker installed" height="100"/>
481
-<img src="res/setup/image-13.png" alt="docker installed" height="100"/>
482
-<br><br>
537
+```env
538
+# Model configuration
539
+A0_SET_chat_model_provider=anthropic
540
+A0_SET_chat_model_name=claude-3-5-sonnet-20241022
541
+A0_SET_chat_model_ctx_length=200000
542
484
-5. Create account in the application.
485
-- It's required to be signed in to the Docker Hub, so create a free account in the Docker Desktop application, you will be prompted when the application first runs.
543
+# Memory settings
544
+A0_SET_memory_recall_enabled=true
545
+A0_SET_memory_recall_interval=5
546
487
-> [!IMPORTANT]
488
-> **Important macOS-only Docker Configuration:** In Docker Desktop's preferences
489
-> (Docker menu) go to Settings, navigate to "Advanced" and check "Allow the default
490
-> Docker socket to be used (requires password)." This allows Agent Zero to
491
-> communicate with the Docker daemon.
547
+# Agent configuration
548
+A0_SET_agent_profile=custom
549
+A0_SET_agent_memory_subdir=production
550
+```
551
493
-
552
+**Docker usage:**
553
495
-> [!NOTE]
496
-> **Linux Users:** You can install both Docker Desktop or docker-ce (Community Edition).
497
-> For Docker Desktop, follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/).
498
-> For docker-ce, follow the instructions [here](https://docs.docker.com/engine/install/).
499
->
500
-> If you're using docker-ce, you will need to add your user to the `docker` group to be able to run docker commands without sudo. You can do this by running the following command in your terminal: `sudo usermod -aG docker $USER`. Then log out and log back in for the changes to take effect.
501
->
502
-> Login in the Docker CLI with `docker login` and provide your Docker Hub credentials.
503
-
504
-6. Pull the Docker image
505
-- Agent Zero needs a Docker image to be pulled from the Docker Hub to be run, even when using the full binaries.
506
-You can refer to the [installation instructions above](#windows-macos-and-linux-setup-guide) to run the Docker container and then resume from the next step. There are two differences:
507
- - You need to map two ports instead of one:
508
- - 55022 in the first field to run the Remote Function Call SSH
509
- - 0 in the second field to run the Web UI in automatic port assignment
510
- - You need to map the `/a0` volume to the location of your local Agent Zero folder.
511
-- Run the Docker container following the instructions.
512
-
513
-## 5. Run the local Agent Zero instance
514
-Run the Agent Zero with Web UI:
515
-~~~
516
-python run_ui.py
517
-~~~
518
-
519
-<img src="res/setup/image-21.png" alt="run ui" height="110"/>
520
-<br><br>
554
+When running Docker, you can pass these as environment variables:
555
522
-- Open the URL shown in terminal in your web browser. You should see the Agent Zero interface.
556
+```bash
557
+docker run -p 50080:80 \
558
+ -e A0_SET_chat_model_provider=anthropic \
559
+ -e A0_SET_chat_model_name=claude-3-5-sonnet-20241022 \
560
+ agent0ai/agent-zero
561
+```
562
524
-## 6. Configure Agent Zero
525
-Now we can configure Agent Zero - select models, settings, API Keys etc. Refer to the [Usage](usage.md#agent-configuration) guide for a full guide on how to configure Agent Zero.
563
+**Notes:**
564
527
-## 7. Configure Agent Zero RFC
528
-Agent Zero needs to be configured further to redirect some functions to the Docker container. This is crucial for development as A0 needs to run in a standardized environment to support all features.
529
-1. Go in "Settings" page in the Web UI of your local instance and go in the "Development" section.
530
-2. Set "RFC Destination URL" to `http://localhost`
531
-3. Set the two ports (HTTP and SSH) to the ones used when creating the Docker container
532
-4. Click "Save"
565
+- 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.
566
+- Sensitive settings (API keys, passwords) use their existing environment variables
567
+- Container/process restart required for changes to take effect
568
534
-
569
+---
570
536
-5. Go in "Settings" page in the Web UI of your Docker instance and go in the "Development" section.
571
+### Manual Migration (Legacy or Non-Docker)
572
538
-
573
+If you are migrating from older, non-Docker setups, copy these directories into `/a0/usr/` in the new instance:
574
540
-6. This time the page has only the password field, set it to the same password you used when creating the Docker container.
541
-7. Click "Save"
542
-8. Use the Development environment
543
-9. Now you have the full development environment to work on Agent Zero.
575
+- `/a0/memory` (agent memories)
576
+- `/a0/knowledge` (custom knowledge)
577
+- `/a0/instruments` (custom instruments)
578
+- `/a0/tmp/settings.json` (settings)
579
+- `/a0/tmp/chats/` (chat history)
580
+- `/a0/tmp/secrets.env` (secrets)
581
545
-<img src="res/setup/image-22-1.png" alt="run ui" width="400"/>
546
-<img src="res/setup/image-23-1.png" alt="run ui" width="400"/>
547
-<br><br>
582
+Then proceed with the Docker installation steps above.
583
+
584
+## Conclusion
585
+
586
+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.
587
549
-
550
-### Conclusion
551
-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.
588
+**Next Steps:**
589
553
-If you encounter any issues during the installation process, please consult the [Troubleshooting section](troubleshooting.md) of this documentation or refer to the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community for assistance.
590
+- For production server deployments, see the [VPS Deployment Guide](vps-deployment.md)
591
+- For development setup and extensions, see the [Development Setup Guide](dev-setup.md)
592
+- For remote access via tunnel, see [Remote Access via Tunneling](../guides/usage.md#remote-access-via-tunneling)
593
594
+If you encounter any issues during the installation process, please consult the [Troubleshooting section](../guides/troubleshooting.md) of this documentation or refer to the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community for assistance.