-- -> [!NOTE] -> **Linux Users:** You can install either Docker Desktop or docker-ce (Community Edition). -> For Docker Desktop, follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/). -> For docker-ce, follow the instructions [here](https://docs.docker.com/engine/install/). -> -> If you're using docker-ce, you'll need to add your user to the `docker` group: -> ```bash -> sudo usermod -aG docker $USER -> ``` -> Log out and back in, then run: -> ```bash -> docker login -> ``` - -1.3. Run the installer with default settings. On macOS, drag and drop the application to your Applications folder. - -
-
-
-
-- -1.4. Once installed, launch Docker Desktop: - -
-
-- -> [!NOTE] -> **MacOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings → -> Advanced, enable "Allow the default Docker socket to be used (requires password)." - - - -2. **Run Agent Zero:** - -- 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. - -2.1. Pull the Agent Zero Docker image: -- Search for `agent0ai/agent-zero` in Docker Desktop -- Click the `Pull` button -- The image will be downloaded to your machine in a few minutes - - - -> [!TIP] -> Alternatively, run the following command in your terminal: -> -> ```bash -> docker pull agent0ai/agent-zero -> ``` - -2.2. OPTIONAL - Create a data directory for persistence: - -> [!CAUTION] -> Preferred way of persisting Agent Zero data is to use the backup and restore feature. -> By mapping the whole `/a0` directory to a local directory, you will run into problems when upgrading Agent Zero to a newer version. - -- Choose or create a directory on your machine where you want to store Agent Zero's data -- This can be any location you prefer (e.g., `C:/agent-zero-data` or `/home/user/agent-zero-data`) -- You can map individual subfolders of `/a0` to a local directory or the full `/a0` directory (not recommended). -- This directory will contain all your Agent Zero files, like the legacy root folder structure: - - `/agents` - Specialized agents with their prompts and tools - - `/memory` - Agent's memory and learned information - - `/knowledge` - Knowledge base - - `/usr/skills` - Skills using the open SKILL.md standard - - `/prompts` - Prompt files - - `.env` - Your API keys - - `/tmp/settings.json` - Your Agent Zero settings - -> [!TIP] -> Choose a location that's easy to access and backup. All your Agent Zero data -> will be directly accessible in this directory. - -### Automated Configuration via Environment Variables - -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. - -**Usage:** -Add variables to your `.env` file in the format: -``` -A0_SET_{setting_name}={value} -``` - -**Examples:** -```env -# Model configuration -A0_SET_chat_model_provider=anthropic -A0_SET_chat_model_name=claude-3-5-sonnet-20241022 -A0_SET_chat_model_ctx_length=200000 - -# Memory settings -A0_SET_memory_recall_enabled=true -A0_SET_memory_recall_interval=5 - -# Agent configuration -A0_SET_agent_profile=custom -A0_SET_agent_memory_subdir=production -``` - -**Docker usage:** -When running Docker, you can pass these as environment variables: -```bash -docker run -p 50080:80 \ - -e A0_SET_chat_model_provider=anthropic \ - -e A0_SET_chat_model_name=claude-3-5-sonnet-20241022 \ - agent0ai/agent-zero -``` - -**Type conversion:** -- Strings are used as-is -- Numbers are automatically converted (e.g., "100000" becomes integer 100000) -- Booleans accept: true/false, 1/0, yes/no, on/off (case-insensitive) -- Dictionaries must be valid JSON (e.g., `{"temperature": "0"}`) - -**Notes:** -- 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. -- Sensitive settings (API keys, passwords) use their existing environment variables -- Container/process restart required for changes to take effect - -2.3. Run the container: -- In Docker Desktop, go back to the "Images" tab -- Click the `Run` button next to the `agent0ai/agent-zero` image -- Open the "Optional settings" menu -- Set the web port (80) to desired host port number in the second "Host port" field or set to `0` for automatic port assignment - -Optionally you can map local folders for file persistence: -> [!CAUTION] -> Preferred way of persisting Agent Zero data is to use the backup and restore feature. -> By mapping the whole `/a0` directory to a local directory, you will run into problems when upgrading Agent Zero to a newer version. -- OPTIONAL: Under "Volumes", configure your mapped folders, if needed: - - Example host path: Your chosen directory (e.g., `C:\agent-zero\memory`) - - Example container path: `/a0/memory` - - -- Click the `Run` button in the "Images" tab. - - - - -- The container will start and show in the "Containers" tab - - - -> [!TIP] -> Alternatively, run the following command in your terminal: -> ```bash -> docker run -p $PORT:80 -v /path/to/your/data:/a0 agent0ai/agent-zero -> ``` -> - Replace `$PORT` with the port you want to use (e.g., `50080`) -> - Replace `/path/to/your/data` with your chosen directory path - -2.4. Access the Web UI: -- The framework will take a few seconds to initialize and the Docker logs will look like the image below. -- Find the mapped port in Docker Desktop (shown as `
+
+ +Windows + + |
+
+
+ +macOS + + |
+
+
+ +Linux + + |
+
Windows Installation
+
+**1.1. Download Docker Desktop**
+
+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).
+
+
++ +**1.2. Run the Installer** + +Run the installer with default settings. + +
+
++ +**1.3. Launch Docker Desktop** + +Once installed, launch Docker Desktop from your Start menu or desktop shortcut. + +
+
+✅ **Docker is now installed!**
+
+### Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero)
+
+---
+
+
+## macOS Installation
+
+**1.1. Download Docker Desktop**
+
+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).
+
+
++ +**1.2. Install Docker Desktop** + +Drag and drop the Docker application to your Applications folder. + +
++ +**1.3. Launch Docker Desktop** + +Open Docker Desktop from your Applications folder. + +
++ +**1.4. Configure Docker Socket** + +> [!NOTE] +> **Important macOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings → Advanced, enable "Allow the default Docker socket to be used (requires password)." + + + +✅ **Docker is now installed!** + +### Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero) + +--- + + +##
Linux Installation
+
+**1.1. Choose Installation Method**
+
+You can install either Docker Desktop or docker-ce (Community Edition).
+
+**Option A: Docker Desktop (Recommended for beginners)**
+
+Follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/).
+
+**Option B: docker-ce (Lightweight alternative)**
+
+Follow the installation instructions [here](https://docs.docker.com/engine/install/).
+
+**1.2. Post-Installation Steps (docker-ce only)**
+
+If you installed docker-ce, add your user to the `docker` group:
+
+```bash
+sudo usermod -aG docker $USER
+```
+
+Log out and back in, then authenticate:
+
+```bash
+docker login
+```
+
+**1.3. Launch Docker**
+
+If you installed Docker Desktop, launch it from your applications menu.
+
+✅ **Docker is now installed!**
+
+> [!TIP]
+> **Deploying on a VPS/Server?** For production deployments with reverse proxy, SSL, and domain configuration, see the [VPS Deployment Guide](vps-deployment.md).
+
+---
+
+## Step 2: Run Agent Zero
+
+### 2.1. Pull the Agent Zero Docker Image
+
+**Using Docker Desktop GUI:**
+
+- Search for `agent0ai/agent-zero` in Docker Desktop
+- Click the `Pull` button
+- The image will be downloaded to your machine in a few minutes
+
+
+
+**Using Terminal:**
+
+```bash
+docker pull agent0ai/agent-zero
+```
+
+### 2.2. (Optional) Map Folders for Persistence
+
+Choose or create a folder on your computer where Agent Zero will save its data.
+
+### Setting up persistence is needed only if you want your data and files to remain available even after you delete the container.
+
+You can pick any location you find convenient:
+
+- **Windows:** `C:\agent-zero-data`
+- **macOS/Linux:** `/home/user/agent-zero-data`
+
+You can map just the `/a0/usr` directory (recommended) or individual subfolders of `/a0` to a local directory.
+
+> [!CAUTION]
+> Do **not** map the entire `/a0` directory: it contains the application code and can break upgrades.
+
+> [!TIP]
+> Choose a location that's easy to access and backup. All your Agent Zero data will be directly accessible in this directory.
+
+### 2.3. Run the Container
+
+**Using Docker Desktop GUI:**
+
+- In Docker Desktop, go to the "Images" tab
+- Click the `Run` button next to the `agent0ai/agent-zero` image
+- Open the "Optional settings" menu
+- **Ensure at least one host port is mapped to container port `80`** (set host port to `0` for automatic assignment)
+- Click the `Run` button
+
+
+
+
+The container will start and show in the "Containers" tab:
+
+
+
+### 2.4. Access the Web UI
+
+The framework will take a few seconds to initialize. Find the mapped port in Docker Desktop (shown as ` Windows Ollama Installation
+
+Download and install Ollama from the official website:
+
+
+
+Once installed, continue to [Pulling Models](#pulling-models).
+
+---
+
+
+### macOS Ollama Installation
+
+**Using Homebrew:**
+
+```bash
+brew install ollama
+```
+
+**Using Installer:**
+
+Download from the [official website](https://ollama.com/).
+
+Once installed, continue to [Pulling Models](#pulling-models).
+
+---
+
+
+### Linux Ollama Installation
+
+Run the installation script:
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+Once installed, continue to [Pulling Models](#pulling-models).
+
+---
+
+### Pulling Models
+
+**Finding Model Names:**
+
+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`).
+
+**Pull a model:**
+
+```bash
+ollama pull
-- **[Installation](installation.md):** Set up (or [update](installation.md#how-to-update-agent-zero)) Agent Zero on your system.
-- **[Usage Guide](usage.md):** Explore GUI features and usage scenarios.
-- **[Architecture Overview](architecture.md):** Understand the internal workings of the framework.
-- **[Contributing](contribution.md):** Learn how to contribute to the Agent Zero project.
-- **[Troubleshooting and FAQ](troubleshooting.md):** Find answers to common issues and questions.
+# `Agent Zero`
-### Your experience with Agent Zero starts now!
+
+[Development Setup](./docs/setup/dev-setup.md) • +[Usage](./docs/guides/usage.md) + +Or see DeepWiki generated documentation: + +[](https://deepwiki.com/agent0ai/agent-zero) + +
+
+
+
+
+
+[Development Setup](./docs/setup/dev-setup.md) • +[Usage](./docs/guides/usage.md) + +Or see DeepWiki generated documentation: + +[](https://deepwiki.com/agent0ai/agent-zero) + +
+
+> ### 🚨 **AGENT ZERO SKILLS** 🚨
+> Agent Zero Instruments become **Skills** - portable, structured agent capabilities using the open `SKILL.md` standard (compatible with Claude Code, Codex and more).
+>
+> **Plus:** Git-based Projects with authentication for public/private repositories - clone codebases directly into isolated workspaces.
+>
+> See [Usage Guide](./docs/guides/usage.md) and [Projects Tutorial](./docs/guides/projects.md) to get started.
+
+
+
+
+[](https://youtu.be/lazLNcEYsiQ)
+
+
+## A personal, organic agentic framework that grows and learns with you
+
+
+
+- Agent Zero is not a predefined agentic framework. It is designed to be dynamic, organically growing, and learning as you use it.
+- Agent Zero is fully transparent, readable, comprehensible, customizable, and interactive.
+- Agent Zero uses the computer as a tool to accomplish its (your) tasks.
+
+# ⚙️ Installation
+
+Click to open a video to learn how to install Agent Zero:
+
+[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
+
+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).
+
+### ⚡ Quick Start
+
+```bash
+# Pull and run with Docker
+
+docker pull agent0ai/agent-zero
+docker run -p 50001:80 agent0ai/agent-zero
+
+# Visit http://localhost:50001 to start
+```
+
+
+# 💡 Key Features
+
+1. **General-purpose Assistant**
+
+- 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.
+- 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.
+
+
+
+2. **Computer as a Tool**
+
+- 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.
+- 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.
+- Tool usage functionality has been developed from scratch to be the most compatible and reliable, even with very small models.
+- **Default Tools:** Agent Zero includes tools like knowledge, code execution, and communication.
+- **Creating Custom Tools:** Extend Agent Zero's functionality by creating your own custom tools.
+- **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.
+
+3. **Multi-agent Cooperation**
+
+- Every agent has a superior agent giving it tasks and instructions. Every agent then reports back to its superior.
+- In the case of the first agent in the chain (Agent 0), the superior is the human user; the agent sees no difference.
+- Every agent can create its subordinate agent to help break down and solve subtasks. This helps all agents keep their context clean and focused.
+
+
+
+4. **Completely Customizable and Extensible**
+
+- Almost nothing in this framework is hard-coded. Nothing is hidden. Everything can be extended or changed by the user.
+- 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.
+- The framework does not guide or limit the agent in any way. There are no hard-coded rails that agents have to follow.
+- Every prompt, every small message template sent to the agent in its communication loop can be found in the **prompts/** folder and changed.
+- Every default tool can be found in the **python/tools/** folder and changed or copied to create new predefined tools.
+- **Automated configuration** via `A0_SET_` environment variables for deployment automation and easy setup.
+
+
+
+5. **Communication is Key**
+
+- Give your agent a proper system prompt and instructions, and it can do miracles.
+- 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.
+- 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.
+- 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.
+
+## 🚀 Real-world use cases
+
+- **Financial Analysis & Charting** - `"Find last month's Bitcoin/USD price trend, correlate with major cryptocurrency news events, generate annotated chart with highlighted key dates"`
+
+- **Excel Automation Pipeline** - `"Scan incoming directory for financial spreadsheets, validate and clean data, consolidate from multiple sources, generate executive reports with flagged anomalies"`
+
+- **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
+
+- **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)
+
+- **Multi-Client Project Isolation** - Separate projects for each client with isolated memory, custom instructions, and dedicated secrets - prevents context bleed across sensitive work
+
+## 🐳 Fully Dockerized, with Speech-to-Text and TTS
+
+
+
+- Customizable settings allow users to tailor the agent's behavior and responses to their needs.
+- The Web UI output is very clean, fluid, colorful, readable, and interactive; nothing is hidden.
+- You can load or save chats directly within the Web UI.
+- The same output you see in the terminal is automatically saved to an HTML file in **logs/** folder for every session.
+
+
+
+- Agent output is streamed in real-time, allowing users to read along and intervene at any time.
+- No coding is required; only prompting and communication skills are necessary.
+- With a solid system prompt, the framework is reliable even with small models, including precise tool usage.
+
+## 👀 Keep in Mind
+
+1. **Agent Zero Can Be Dangerous!**
+
+- 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.
+
+2. **Agent Zero Is Prompt-based.**
+
+- The whole framework is guided by the **prompts/** folder. Agent guidelines, tool instructions, messages, utility AI functions, it's all there.
+
+
+## 📚 Read the Documentation
+
+| Page | Description |
+|-------|-------------|
+| [Installation](./docs/setup/installation.md) | Installation, setup and configuration |
+| [Usage](./docs/guides/usage.md) | Basic and advanced usage |
+| [Guides](./docs/guides/) | Step-by-step guides: Usage, Projects, API Integration, MCP Setup, A2A Setup |
+| [Development Setup](./docs/setup/dev-setup.md) | Development and customization |
+| [WebSocket Infrastructure](./docs/developer/websockets.md) | Real-time WebSocket handlers, client APIs, filtering semantics, envelopes |
+| [Extensions](./docs/developer/extensions.md) | Extending Agent Zero |
+| [Connectivity](./docs/developer/connectivity.md) | External API endpoints, MCP server connections, A2A protocol |
+| [Architecture](./docs/developer/architecture.md) | System design and components |
+| [Contributing](./docs/guides/contribution.md) | How to contribute |
+| [Troubleshooting](./docs/guides/troubleshooting.md) | Common issues and their solutions |
+
+
+## 🎯 Changelog
+
+### v0.9.8 - Skills, UI Redesign & Git projects
+[Release video](https://youtu.be/NV7s78yn6DY)
+
+- Skills
+ - Skills System replacing the legacy Instruments with a new `SKILL.md` standard for structured, portable agent capabilities.
+ - Built-in skills, and UI support for importing and listing skills
+- Real-time WebSocket infrastructure replacing the polling-based approach for UI state synchronization
+- UI Redesign
+ - Process groups to visually group agent actions with expand/collapse support
+ - Timestamps, steps count and execution time with tool-specific badges
+ - Step detail modals with key-value and raw JSON display
+ - Collapsible responses with show more/less and copy buttons on code blocks and tables
+ - Message queue system allowing users to queue messages while the agent is still processing
+ - In-browser file editor for viewing and editing files without leaving the UI
+ - Welcome screen redesign with info and warning banners for connection security, missing API keys, and system resources
+ - Scheduler redesign with standalone modal, separate task list, detail and editor components, and project support
+ - Smooth response rendering and scroll stabilization across chat, terminals, and image viewer
+ - Chat width setting and reworked preferences panel
+ - Image viewer improvements with scroll support and expanded viewer
+ - Redesigned sidebar with reusable dropdown component and streamlined buttons
+ - Inline button confirmations for critical actions
+ - Improved login design and new logout button
+ - File browser enhanced with rename and file actions dropdown
+- Git projects
+ - Git-based projects with clone authentication for public and private repositories
+- Four new LLM providers: CometAPI, Z.AI, Moonshot AI, and AWS Bedrock
+- Microsoft Dev Tunnels integration for secure remote access
+- User data migration to `/usr` directory for cleaner separation of user and system files
+- Subagents system with configurable agent profiles for different roles
+- Memory operations offloaded to deferred tasks for better performance
+- Environment variables can now configure settings via `A0_SET_*` prefix in `.env`
+- Automatic migration with overwrite support for `.env`, scheduler, knowledge, and legacy instruments directories
+- Projects support extended to MCP, A2A, and external API
+- Workdir outside project support for more flexible file organization
+- Agent number tracking in backend and responses for multi-agent identification
+- Many bug fixes and stability improvements across the UI, MCP tools, scheduler, uploads, and WebSocket handling
+
+
+### v0.9.7 - Projects
+[Release video](https://youtu.be/RrTDp_v9V1c)
+- Projects management
+ - Support for custom instructions
+ - Integration with memory, knowledge, files
+ - Project specific secrets
+- New Welcome screen/Dashboard
+- New Wait tool
+- Subordinate agent configuration override support
+- Support for multiple documents at once in document_query_tool
+- Improved context on interventions
+- Openrouter embedding support
+- Frontend components refactor and polishing
+- SSH metadata output fix
+- Support for windows powershell in local TTY utility
+- More efficient selective streaming for LLMs
+- UI output length limit improvements
+
+### v0.9.6 - Memory Dashboard
+[Release video](https://youtu.be/sizjAq2-d9s)
+- Memory Management Dashboard
+- Kali update
+- Python update + dual installation
+- Browser Use update
+- New login screen
+- LiteLLM retry on temporary errors
+- Github Copilot provider support
+
+### v0.9.5 - Secrets
+[Release video](https://www.youtube.com/watch?v=VqxUdt7pjd8)
+- Secrets management - agent can use credentials without seeing them
+- Agent can copy paste messages and files without rewriting them
+- LiteLLM global configuration field
+- Custom HTTP headers field for browser agent
+- Progressive web app support
+- Extra model params support for JSON
+- Short IDs for files and memories to prevent LLM errors
+- Tunnel component frontend rework
+- Fix for timezone change bug
+- Notifications z-index fix
+
+### v0.9.4 - Connectivity, UI
+[Release video](https://www.youtube.com/watch?v=C2BAdDOduIc)
+- External API endpoints
+- Streamable HTTP MCP A0 server
+- A2A (Agent to Agent) protocol - server+client
+- New notifications system
+- New local terminal interface for stability
+- Rate limiter integration to models
+- Delayed memory recall
+- Smarter autoscrolling in UI
+- Action buttons in messages
+- Multiple API keys support
+- Download streaming
+- Tunnel URL QR code
+- Internal fixes and optimizations
+
+### v0.9.3 - Subordinates, memory, providers Latest
+[Release video](https://www.youtube.com/watch?v=-LfejFWL34k)
+- Faster startup/restart
+- Subordinate agents can have dedicated prompts, tools and system extensions
+- Streamable HTTP MCP server support
+- Memory loading enhanced by AI filter
+- Memory AI consolidation when saving memories
+- Auto memory system configuration in settings
+- LLM providers available are set by providers.yaml configuration file
+- Venice.ai LLM provider supported
+- Initial agent message for user + as example for LLM
+- Docker build support for local images
+- File browser fix
+
+### v0.9.2 - Kokoro TTS, Attachments
+[Release video](https://www.youtube.com/watch?v=sPot_CAX62I)
+
+- Kokoro text-to-speech integration
+- New message attachments system
+- Minor updates: log truncation, hyperlink targets, component examples, api cleanup
+
+### v0.9.1 - LiteLLM, UI improvements
+[Release video](https://youtu.be/crwr0M4Spcg)
+- Langchain replaced with LiteLLM
+ - Support for reasoning models streaming
+ - Support for more providers
+ - Openrouter set as default instead of OpenAI
+- UI improvements
+ - New message grouping system
+ - Communication smoother and more efficient
+ - Collapsible messages by type
+ - Code execution tool output improved
+ - Tables and code blocks scrollable
+ - More space efficient on mobile
+- Streamable HTTP MCP servers support
+- LLM API URL added to models config for Azure, local and custom providers
+
+### v0.9.0 - Agent roles, backup/restore
+[Release video](https://www.youtube.com/watch?v=rMIe-TC6H-k)
+- subordinate agents can use prompt profiles for different roles
+- backup/restore functionality for easier upgrades
+- security and bug fixes
+
+### v0.8.7 - Formatting, Document RAG Latest
+[Release video](https://youtu.be/OQJkfofYbus)
+- markdown rendering in responses
+- live response rendering
+- document Q&A tool
+
+### v0.8.6 - Merge and update
+[Release video](https://youtu.be/l0qpK3Wt65A)
+- Merge with Hacking Edition
+- browser-use upgrade and integration re-work
+- tunnel provider switch
+
+### v0.8.5 - **MCP Server + Client**
+[Release video](https://youtu.be/pM5f4Vz3_IQ)
+
+- Agent Zero can now act as MCP Server
+- Agent Zero can use external MCP servers as tools
+
+### v0.8.4.1 - 2
+Default models set to gpt-4.1
+- Code execution tool improvements
+- Browser agent improvements
+- Memory improvements
+- Various bugfixes related to context management
+- Message formatting improvements
+- Scheduler improvements
+- New model provider
+- Input tool fix
+- Compatibility and stability improvements
+
+### v0.8.4
+[Release video](https://youtu.be/QBh_h_D_E24)
+
+- **Remote access (mobile)**
+
+### v0.8.3.1
+[Release video](https://youtu.be/AGNpQ3_GxFQ)
+
+- **Automatic embedding**
+
+### v0.8.3
+[Release video](https://youtu.be/bPIZo0poalY)
+
+- ***Planning and scheduling***
+
+### v0.8.2
+[Release video](https://youtu.be/xMUNynQ9x6Y)
+
+- **Multitasking in terminal**
+- **Chat names**
+
+### v0.8.1
+[Release video](https://youtu.be/quv145buW74)
+
+- **Browser Agent**
+- **UX Improvements**
+
+### v0.8
+[Release video](https://youtu.be/cHDCCSr1YRI)
+
+- **Docker Runtime**
+- **New Messages History and Summarization System**
+- **Agent Behavior Change and Management**
+- **Text-to-Speech (TTS) and Speech-to-Text (STT)**
+- **Settings Page in Web UI**
+- **SearXNG Integration Replacing Perplexity + DuckDuckGo**
+- **File Browser Functionality**
+- **KaTeX Math Visualization Support**
+- **In-chat File Attachments**
+
+### v0.7
+[Release video](https://youtu.be/U_Gl0NPalKA)
+
+- **Automatic Memory**
+- **UI Improvements**
+- **Instruments**
+- **Extensions Framework**
+- **Reflection Prompts**
+- **Bug Fixes**
+
+## 🤝 Community and Support
+
+- [Join our Discord](https://discord.gg/B8KZKNsPpj) for live discussions or [visit our Skool Community](https://www.skool.com/agent-zero).
+- [Follow our YouTube channel](https://www.youtube.com/@AgentZeroFW) for hands-on explanations and tutorials
+- [Report Issues](https://github.com/agent0ai/agent-zero/issues) for bug fixes and features
diff --git a/knowledge/main/about/installation.md b/knowledge/main/about/installation.md
index 5cbaea5e1..4c25568ce 100644
--- a/knowledge/main/about/installation.md
+++ b/knowledge/main/about/installation.md
@@ -1,554 +1,594 @@
-# Users installation guide for Windows, macOS and Linux
+# Installation Guide
Click to open a video to learn how to install Agent Zero:
-[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
+[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
-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).
+## **Goal:** Go from zero to a first working chat with minimal setup.
-## Windows, macOS and Linux Setup Guide
+## Step 1: Install Docker Desktop
+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.
-1. **Install Docker Desktop:**
-- 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
-- Available as a user-friendly GUI application for all major operating systems
+**Choose your operating system:**
-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".
+|
+
+ +Windows + + |
+
+
+ +macOS + + |
+
+
+ +Linux + + |
+
+
+## Windows Installation
+
+**1.1. Download Docker Desktop**
+
+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).
+
+
+**1.2. Run the Installer** + +Run the installer with default settings. + +
+
++ +**1.3. Launch Docker Desktop** + +Once installed, launch Docker Desktop from your Start menu or desktop shortcut. + +
+
+✅ **Docker is now installed!**
+
+### Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero)
+
+---
+
+
+## macOS Installation
+
+**1.1. Download Docker Desktop**
+
+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).
+
+
++ +**1.2. Install Docker Desktop** + +Drag and drop the Docker application to your Applications folder. + +
++ +**1.3. Launch Docker Desktop** + +Open Docker Desktop from your Applications folder. + +
++ +**1.4. Configure Docker Socket** + > [!NOTE] -> **Linux Users:** You can install either Docker Desktop or docker-ce (Community Edition). -> For Docker Desktop, follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/). -> For docker-ce, follow the instructions [here](https://docs.docker.com/engine/install/). -> -> If you're using docker-ce, you'll need to add your user to the `docker` group: -> ```bash -> sudo usermod -aG docker $USER -> ``` -> Log out and back in, then run: -> ```bash -> docker login -> ``` +> **Important macOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings → Advanced, enable "Allow the default Docker socket to be used (requires password)." -1.3. Run the installer with default settings. On macOS, drag and drop the application to your Applications folder. + -
-
+✅ **Docker is now installed!**
-
-+### Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero) -1.4. Once installed, launch Docker Desktop: +--- -
-
-+ +##
Linux Installation
-> [!IMPORTANT]
-> **macOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings →
-> Advanced, enable "Allow the default Docker socket to be used (requires password)."
+**1.1. Choose Installation Method**
-
+You can install either Docker Desktop or docker-ce (Community Edition).
-2. **Run Agent Zero:**
+**Option A: Docker Desktop (Recommended for beginners)**
-- 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.
+Follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/).
+
+**Option B: docker-ce (Lightweight alternative)**
+
+Follow the installation instructions [here](https://docs.docker.com/engine/install/).
+
+**1.2. Post-Installation Steps (docker-ce only)**
+
+If you installed docker-ce, add your user to the `docker` group:
+
+```bash
+sudo usermod -aG docker $USER
+```
+
+Log out and back in, then authenticate:
+
+```bash
+docker login
+```
+
+**1.3. Launch Docker**
+
+If you installed Docker Desktop, launch it from your applications menu.
+
+✅ **Docker is now installed!**
+
+> [!TIP]
+> **Deploying on a VPS/Server?** For production deployments with reverse proxy, SSL, and domain configuration, see the [VPS Deployment Guide](vps-deployment.md).
+
+---
+
+## Step 2: Run Agent Zero
+
+### 2.1. Pull the Agent Zero Docker Image
+
+**Using Docker Desktop GUI:**
-2.1. Pull the Agent Zero Docker image:
- Search for `agent0ai/agent-zero` in Docker Desktop
- Click the `Pull` button
- The image will be downloaded to your machine in a few minutes
-
+
+
+**Using Terminal:**
+
+```bash
+docker pull agent0ai/agent-zero
+```
+
+### 2.2. (Optional) Map Folders for Persistence
+
+Choose or create a folder on your computer where Agent Zero will save its data.
+
+### Setting up persistence is needed only if you want your data and files to remain available even after you delete the container.
+
+You can pick any location you find convenient:
+
+- **Windows:** `C:\agent-zero-data`
+- **macOS/Linux:** `/home/user/agent-zero-data`
+
+You can map just the `/a0/usr` directory (recommended) or individual subfolders of `/a0` to a local directory.
+
+> [!CAUTION]
+> Do **not** map the entire `/a0` directory: it contains the application code and can break upgrades.
> [!TIP]
-> Alternatively, run the following command in your terminal:
->
-> ```bash
-> docker pull agent0ai/agent-zero
-> ```
+> Choose a location that's easy to access and backup. All your Agent Zero data will be directly accessible in this directory.
-2.2. Create a data directory for persistence:
-- Choose or create a directory on your machine where you want to store Agent Zero's data
-- This can be any location you prefer (e.g., `C:/agent-zero-data` or `/home/user/agent-zero-data`)
-- This directory will contain all your Agent Zero files, like the legacy root folder structure:
- - `/memory` - Agent's memory and learned information
- - `/knowledge` - Knowledge base
- - `/instruments` - Instruments and functions
- - `/prompts` - Prompt files
- - `/work_dir` - Working directory
- - `.env` - Your API keys
- - `settings.json` - Your Agent Zero settings
+### 2.3. Run the Container
-> [!TIP]
-> Choose a location that's easy to access and backup. All your Agent Zero data
-> will be directly accessible in this directory.
+**Using Docker Desktop GUI:**
-2.3. Run the container:
-- In Docker Desktop, go back to the "Images" tab
+- In Docker Desktop, go to the "Images" tab
- Click the `Run` button next to the `agent0ai/agent-zero` image
- Open the "Optional settings" menu
-- Set the port to `0` in the second "Host port" field (for automatic port assignment)
+- **Ensure at least one host port is mapped to container port `80`** (set host port to `0` for automatic assignment)
+- Click the `Run` button
-Optionally you can map local folders for file persistence:
-- Under "Volumes", configure:
- - Host path: Your chosen directory (e.g., `C:\agent-zero-data`)
- - Container path: `/a0`
+
+
-
+The container will start and show in the "Containers" tab:
-- Click the `Run` button in the "Images" tab.
-- The container will start and show in the "Containers" tab
+
-
+### 2.4. Access the Web UI
+
+The framework will take a few seconds to initialize. Find the mapped port in Docker Desktop (shown as ` Windows Ollama Installation
+
+Download and install Ollama from the official website:
-**On macOS:**
-```
+Once installed, continue to [Pulling Models](#pulling-models).
+
+---
+
+
+### macOS Ollama Installation
+
+**Using Homebrew:**
+
+```bash
brew install ollama
```
-Otherwise choose macOS installer from the [official website](https://ollama.com/).
-**On Linux:**
+**Using Installer:**
+
+Download from the [official website](https://ollama.com/).
+
+Once installed, continue to [Pulling Models](#pulling-models).
+
+---
+
+
+### Linux Ollama Installation
+
+Run the installation script:
+
```bash
curl -fsSL https://ollama.com/install.sh | sh
```
-**Finding Model Names:**
-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).
+Once installed, continue to [Pulling Models](#pulling-models).
-#### Second step: pulling the model
-**On Windows, macOS, and Linux:**
-```
+---
+
+### Pulling Models
+
+**Finding Model Names:**
+
+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`).
+
+**Pull a model:**
+
+```bash
ollama pull 
-
-- -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. - -
-
-
-
-- -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. - -
-
-- - -## 2. Download Agent Zero -- 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. - -1. Go to the Agent Zero releases [here](https://github.com/agent0ai/agent-zero/releases). -2. The latest release is on the top of the list, click the "Source Code (zip)" button under "Assets" to download it. - -
-- -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. - -## 3. Set up Conda environment -- Now that we have the project files and Conda, we can create **virtual Python environment** for this project, activate it and install requirements. - -1. Open your **"Anaconda Powershell Prompt"** application on windows or **"Terminal"** application on macOS. -2. In the terminal, navigate to your Agent Zero folder using **"cd"** command. Replace the path with your actual Agent Zero folder path. -~~~ -cd C:\Users\frdel\Desktop\agent-zero -~~~ -You should see your folder has changed on the next terminal line. - -
-
-- -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. -~~~ -conda create -n a0 python=3.12 -y -~~~ - -4. Once done, activate the new environment for this terminal window by another command: -~~~ -conda activate a0 -~~~ -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. - -
-
-- -> [!IMPORTANT] -> If you open a new terminal window, you will need to activate the environment with -> "conda activate a0" again for that window. - -5. Install requirements using **"pip"**. Pip is a Python package manager. We can install all required packages from requirements.txt file using command: -~~~ -pip install -r requirements.txt -~~~ -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. - -
-- -## 4. Install Docker (Docker Desktop application) -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. -- Agent Zero only connects to the Docker container when it needs to execute code and commands. The frameworks itself runs on your machine. -- Docker has a desktop application with GUI for all major operating system, which is the recommended way to install it. - -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". -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. - -
-- -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. - -
-
-
-
-- - -4. Once installed, you should see Docker Desktop application on your Windows/Mac machine. - -
-
-- -5. Create account in the application. -- 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. - -> [!IMPORTANT] -> **Important macOS-only Docker Configuration:** In Docker Desktop's preferences -> (Docker menu) go to Settings, navigate to "Advanced" and check "Allow the default -> Docker socket to be used (requires password)." This allows Agent Zero to -> communicate with the Docker daemon. - - +## How to Update Agent Zero > [!NOTE] -> **Linux Users:** You can install both Docker Desktop or docker-ce (Community Edition). -> For Docker Desktop, follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/). -> For docker-ce, follow the instructions [here](https://docs.docker.com/engine/install/). -> -> 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. -> -> Login in the Docker CLI with `docker login` and provide your Docker Hub credentials. +> Since v0.9, Agent Zero includes a Backup & Restore workflow in the Settings UI. This is the **safest** way to upgrade Docker instances. -6. Pull the Docker image -- Agent Zero needs a Docker image to be pulled from the Docker Hub to be run, even when using the full binaries. -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: - - You need to map two ports instead of one: - - 55022 in the first field to run the Remote Function Call SSH - - 0 in the second field to run the Web UI in automatic port assignment - - You need to map the `/a0` volume to the location of your local Agent Zero folder. -- Run the Docker container following the instructions. +### Recommended Update Process (Docker) -## 5. Run the local Agent Zero instance -Run the Agent Zero with Web UI: -~~~ -python run_ui.py -~~~ +1. **Keep the old container running** and note its port. +2. **Pull the new image** (`agent0ai/agent-zero:latest`). +3. **Start a new container** on a different host port. +4. In the **old** instance, open **Settings → Backup & Restore** and create a backup. +5. In the **new** instance, restore that backup from the same panel. -
-+> [!TIP] +> If the new instance fails to load settings, remove `/a0/usr/settings.json` and restart to regenerate default settings. -- Open the URL shown in terminal in your web browser. You should see the Agent Zero interface. +--- -## 6. Configure Agent Zero -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. +## Using Agent Zero on Your Mobile Device -## 7. Configure Agent Zero RFC -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. -1. Go in "Settings" page in the Web UI of your local instance and go in the "Development" section. -2. Set "RFC Destination URL" to `http://localhost` -3. Set the two ports (HTTP and SSH) to the ones used when creating the Docker container -4. Click "Save" +Agent Zero can be accessed from mobile devices and other computers using the built-in **Tunnel feature**. - +### Recommended: Using Tunnel (Remote Access) -5. Go in "Settings" page in the Web UI of your Docker instance and go in the "Development" section. +The Tunnel feature allows secure access to your Agent Zero instance from anywhere: - +1. Open Settings in the Web UI +2. Navigate to the **External Services** tab +3. Click on **Flare Tunnel** in the navigation menu +4. Click **Create Tunnel** to generate a secure HTTPS URL +5. Share this URL to access Agent Zero from any device -6. This time the page has only the password field, set it to the same password you used when creating the Docker container. -7. Click "Save" -8. Use the Development environment -9. Now you have the full development environment to work on Agent Zero. +> [!IMPORTANT] +> **Security:** Always set a username and password in Settings → Authentication before creating a tunnel to secure your instance on the internet. -
-
-+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. - -### Conclusion -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. +### Alternative: Local Network Access -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. +If you prefer to keep access limited to your local network: +1. Find the mapped port in Docker Desktop (format: `