docs: update for v.0.8 (#262)

* docs: update for v.0.8

- fix: imgs in setup guide
- updated docs in knowledge dir
- new video in main readme

* Update installation.md with Ollama guide

To be improved asap

* ollama guide

* improving readme and stt/tts

README.md

@@ -2,116 +2,128 @@
 
 [![Join our Skool Community](https://img.shields.io/badge/Skool-Join%20our%20Community-4A90E2?style=for-the-badge&logo=skool&logoColor=white)](https://www.skool.com/agent-zero) [![Join our Discord](https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/B8KZKNsPpj) [![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/@AgentZeroFW) [![Connect on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/jan-tomasek/) [![Follow on X.com](https://img.shields.io/badge/X.com-Follow-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/JanTomasekDev)
 
-
 [![Intro Video](/docs/res/new_vid.jpg)](https://www.youtube.com/watch?v=U_Gl0NPalKA)
 
 **Personal and organic AI framework**
+
 - 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 is fully transparent, readable, comprehensible, customizable, and interactive.
 - Agent Zero uses the computer as a tool to accomplish its (your) tasks.
 
-## Now with Responsive UI, Auto-memory and Reflection:
-![Web UI](/docs/res/win_webui2.gif)
-
-## Key concepts
-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, webpage content, code execution, and communication. 
-* **Creating Custom Tools:**  Extend Agent Zero's functionality by creating your own custom tools.
-* **Instruments:**  Instruments are a new type of tool that allow you to create custom functions and procedures that can be called by Agent Zero.
-
-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.
-- Of course, it is open-source (except for some tools like Perplexity, but that will be replaced with an open-source alternative as well in the future).
-
-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.
+## Now fully Dockerized, with TTS and STT:
+
+![Dockerized Agent Zero](https://github.com/user-attachments/assets/58e5462b-481d-4f43-8a4c-e989b9acfdf7)
+
+## Key Concepts
+
+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, webpage content, code execution, and communication.
+   * **Creating Custom Tools:** Extend Agent Zero's functionality by creating your own custom tools.
+   * **Instruments:** Instruments are a new type of tool that allow you to create custom functions and procedures that can be called by Agent Zero.
+
+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.
+   - Of course, it is open-source (except for some tools like Perplexity, but that will be replaced with an open-source alternative as well in the future).
+
+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.
 
 ![Agent Zero](/docs/res/splash_wide.png)
 
-## Nice features to have
-- Output is very clean, colorful, readable and interactive; nothing is hidden.
-- The same colorful output you see in the terminal is automatically saved to HTML file in **logs/** folder for every session.
-- Agent output is streamed in real-time, allowing the user to read along and intervene at any time.
-- No coding is required, only prompting and communication skills.
+## Nice Features to Have
+
+- The new GUI output is very clean, fluid, colorful, readable, and interactive; nothing is hidden.
+- The same colorful 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.
 
 ![Agent 1 System Load](/docs/res/ui_screen.png)
 
-## Keep in mind
-1. **Agent Zero can be dangerous!**
-With proper instruction, Agent Zero is capable of many things, even potentially dangerous to your computer, data, or accounts. Always run Agent Zero in an isolated environment (like the built in docker container) and be careful what you wish for.
+## 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 not pre-programmed; it is prompt-based.**
-The whole framework contains only a minimal amount of code and does not guide the agent in any way.
-Everything lies in the system prompt in the **prompts/** folder. Here you can rewrite the whole framework behavior to your needs.
-If your agent fails to communicate properly, use tools, reason, use memory, find answers - just instruct it better.
+2. **Agent Zero Is Not Pre-programmed; It Is Prompt-based.**
+   - The whole framework contains only a minimal amount of code and does not guide the agent in any way. Everything lies in the system prompt located in the **prompts/** folder.
 
-3. **If you cannot provide the ideal environment, let your agent know.**
-Agent Zero is made to be used in an isolated virtual environment (for safety) with some tools preinstalled and configured.
-If you cannot provide all the necessary conditions or API keys, just change the system prompt and tell your agent what operating system and tools are at its disposal. Nothing is hard-coded; if you do not tell your agent about a certain tool, it will not know about it and will not try to use it.
+3. **If You Cannot Provide the Ideal Environment, Let Your Agent Know.**
+   - Agent Zero is made to be used in an isolated virtual environment (for safety) with some tools preinstalled and configured.
 
 [![David Ondrej video](/docs/res/david_vid.jpg)](https://www.youtube.com/watch?v=_Pionjv4hGc)
 
-## Known problems
-1. The system prompt sucks. You can do better. If you do, help me please :)
-2. The communication between agents and terminal in Docker Container via SSH can sometimes break and stop producing outputs. Sometimes it is because the agent runs something like "server.serve_forever()" which causes the terminal to hang, sometimes a random error can occur. Restarting the agent and/or the docker container helps.
-3. The agent can break his operating system. Sometimes the agent can deactivate virtual environment, uninstall packages, change config etc. Again, removing the docker container and cleaning up the **work_dir/** is enough to fix that.
+## Known Problems
+
+1. The system prompt may need improvements; contributions are welcome!
+2. Communication between agents via SSH within Docker containers may occasionally break; restarting might resolve issues.
+3. The agent may inadvertently alter its operating environment; cleaning up the **work_dir/** often fixes this.
 
-## Ideal environment
-- **Docker container**: The perfect environment to run Agent Zero is the built-in docker container. The agent can download the image **frdel/agent-zero-exe** on its own and start the container, you only need to have docker running (like the Docker Desktop application).
-- **Python**: Python has to be installed on the system to run the framework.
-- **Internet access**: The agent will need internet access to use its online knowledge tool and execute commands and scripts requiring a connection. If you do not need your agent to be online, you can alter its prompts in the **prompts/** folder and make it fully local.
+## Ideal Environment
+
+- **Docker Container**: The ideal environment for running Agent Zero is within a Docker container; ensure Docker is running (e.g., Docker Desktop).
+- **Internet Access**: Required for online knowledge tools; adjust prompts if offline operation is preferred.
 
 ![Time example](/docs/res/time_example.jpg)
 
 ## Setup
-A detailed setup guide for Windows, macOS and Linux with a video can be found in the new Agent Zero Documentation at [this page](docs/installation.md#in-depth-guide-for-windows-and-macos).
+
+A detailed setup guide for Windows, macOS, and Linux with a video can be found in the new Agent Zero Documentation at [this page](docs/installation.md#windows-macos-and-linux-setup-guide).
+
+You can download full binaries for your system from the [releases page](https://github.com/frdel/agent-zero/releases).
 
 ## Consult the Documentation
-The documentation dives deep into the framework and its features. It is a good place to start if you are new to Agent Zero. Click [here](docs/README.md) to see the Documentation.
 
-## Coming up
-- **Preinstalled binaries and bundler scripts**
-- **Knowledge tool open-sourcing and web scraping tool**
-- **User interaction refinements**
-- **In-context switchable LLMs**
+The documentation dives deep into the framework's features; it's an excellent starting point for new users. Click [here](docs/README.md) for more information.
+
+## Coming Up
+
+- **User Interaction Refinements**
+- **Browser Use and RAG Tools**
 
 ### Changelog [since version 0.7]
 
-#### v0.7.1
-- **Persistent Chats** - Serialized to /tmp/chats and automatically loaded in run_ui.py on startup
-- **Documentation stack merged into the repository**
-- **Bug Fixes**
+> [!IMPORTANT]
+>
+> **Changes to frdel/agent-zero Docker image since v0.8:**
+>
+> - In version 0.8, the Docker image has changed to frdel/agent-zero-run using a new Dockerfile and image.
+
+#### v0.8
+- **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 Knowledge Tool**
+- **File Browser Functionality**
+- **KaTeX Math Visualization Support**
+- **In-chat File Attachments**
 
 #### v0.7
-- **Automatic memory**
-- **UI improvements**
+- **Automatic Memory**
+- **UI Improvements**
 - **Instruments**
-- **Extensions framework**
-- **Reflection prompts**
-- **Bugfixes**
-
-> [!NOTE]  
-> **Changes to launch files since v0.6:**  
-> - main.py file has been replaced with run_ui.py (webui) and run_cli.py (terminal) launch files.
-> - configuration has been moved to initialize.py for both webui and terminal launch files.
+- **Extensions Framework**
+- **Reflection Prompts**
+- **Bug Fixes**

docs/README.md

@@ -3,80 +3,62 @@
 To begin with Agent Zero, follow the links below for detailed guides on various topics:
 
 - **[Installation](installation.md):** Set up (or [update](installation.md#how-to-update-agent-zero)) Agent Zero on your system.
-- **[Quick Start](quickstart.md):** Begin using Agent Zero with practical examples.
-- **[Usage Guide](usage.md):** Explore advanced features and capabilities.
+- **[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.
-##
+
 ### Your experience with Agent Zero starts now!
 
-- **Download Agent Zero:** Download the latest release from the [GitHub releases page](https://github.com/frdel/agent-zero/releases).
+- **Download Agent Zero:** Follow the [installation guide](installation.md) to download and run Agent Zero.
 - **Join the Community:** Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/Z2tun2N3) community to discuss ideas, ask questions, and collaborate with other contributors.
 - **Share your Work:** Share your Agent Zero creations, workflows and discoverings on our [Show and Tell](https://github.com/frdel/agent-zero/discussions/categories/show-and-tell) area on GitHub.
 - **Report Issues:** Use the [GitHub issue tracker](https://github.com/frdel/agent-zero/issues) to report framework-relative bugs or suggest new features.
-##
+
 ## Table of Contents
 
 - [Welcome to the Agent Zero Documentation](#agent-zero-documentation)
-  - [Key Features](#key-features)
-    - [Start your experience with Agent Zero](#your-experience-with-agent-zero-starts-now)
+  - [Your Experience with Agent Zero](#your-experience-with-agent-zero-starts-now)
   - [Table of Contents](#table-of-contents)
-- [Installation guide for Windows, MacOS and Linux](installation.md)
-  - [Windows Quick Start](installation.md#windows-quick-start)
-  - [macOS Quick Start](installation.md#macos-quick-start)
-  - [Linux Quick Start](installation.md#linux-quick-start)
-  - [In-Depth Guide for Windows and MacOS](installation.md#in-depth-guide-for-windows-and-macos)
-    - [1. Install Conda (miniconda)](installation.md#1-install-conda-miniconda)
-    - [2. Install Docker (Docker Desktop application)](installation.md#2-install-docker-docker-desktop-application)
-    - [3. Download Agent Zero](installation.md#3-download-agent-zero)
-    - [4. Set up Conda environment](installation.md#4-set-up-conda-environment)
-    - [5. Configure Agent Zero](installation.md#5-configure-agent-zero)
-    - [6. Run Agent Zero](installation.md#6-run-agent-zero)
-    - [Choosing Your LLMs](installation.md#choosing-your-llms)
-      - [Installing and Using Ollama](installation.md#installing-and-using-ollama-local-models)
-    - [How to update Agent Zero](installation.md#how-to-update-agent-zero)
-    - [How to create executable files for Agent Zero](installation.md#how-to-create-executable-files-for-agent-zero-in-windows-macos-and-linux)
-    - [Conclusion](installation.md#conclusion)
-- [Quick Start](quickstart.md)
-  - [Launching the Web UI](quickstart.md#launching-the-web-ui)
-  - [Running a Simple Task](quickstart.md#running-a-simple-task)
-  - [Example Interaction](quickstart.md#example-interaction)
-  - [Next Steps](quickstart.md#next-steps)
+- [Installation Guide](installation.md)
+  - [Windows, macOS and Linux Setup](installation.md#windows-macos-and-linux-setup-guide)
+  - [Settings Configuration](installation.md#settings-configuration)
+  - [Choosing Your LLMs](installation.md#choosing-your-llms)
+  - [Installing and Using Ollama](installation.md#installing-and-using-ollama-local-models)
+  - [Using Agent Zero on Mobile](installation.md#using-agent-zero-on-your-mobile-device)
+  - [How to Update Agent Zero](installation.md#how-to-update-agent-zero)
+  - [Full Binaries Installation](installation.md#in-depth-guide-for-full-binaries-installation)
 - [Usage Guide](usage.md)
+  - [Basic Operations](usage.md#basic-operations)
+    - [Restart Framework](usage.md#restart-framework)
+    - [Action Buttons](usage.md#action-buttons)
+    - [File Attachments](usage.md#file-attachments)
   - [Tool Usage](usage.md#tool-usage)
-  - [Prompt Engineering](usage.md#prompt-engineering)
   - [Example of Tools Usage](usage.md#example-of-tools-usage-web-search-and-code-execution)
-  - [Memory Management](usage.md#memory-management)
   - [Multi-Agent Cooperation](usage.md#multi-agent-cooperation)
-  - [Agent Behavior](usage.md#agent-behavior)
-  - [Using Agent Zero on your mobile device](usage.md#using-agent-zero-on-your-mobile-device)
-  - [Using code_execution_tool outside of the Docker Container](usage.md#using-code_execution_tool-outside-of-the-docker-container)
+  - [Prompt Engineering](usage.md#prompt-engineering)
+  - [Voice Interface](usage.md#voice-interface)
+  - [Mathematical Expressions](usage.md#mathematical-expressions)
+  - [File Browser](usage.md#file-browser)
 - [Architecture Overview](architecture.md)
+  - [System Architecture](architecture.md#system-architecture)
+  - [Runtime Architecture](architecture.md#runtime-architecture)
   - [Core Components](architecture.md#core-components)
-  - [Agent Hierarchy and Communication](architecture.md#agent-hierarchy-and-communication)
-  - [Interaction Flow](architecture.md#interaction-flow)
-  - [Memory System](architecture.md#memory-system)
-  - [Tools](architecture.md#tools)
-  - [Knowledge](architecture.md#knowledge)
-  - [Prompts](architecture.md#prompts)
-  - [Extensions](architecture.md#extensions)
-    - [Structure of Extensions](architecture.md#structure-of-extensions)
-    - [Types of Default Extensions](architecture.md#types-of-default-extensions)
-  - [Key Files](architecture.md#key-files)
-  - [Directory Structure](architecture.md#directory-structure)
+    - [Agents](architecture.md#1-agents)
+    - [Tools](architecture.md#2-tools)
+    - [SearXNG Integration](architecture.md#searxng-integration)
+    - [Memory System](architecture.md#3-memory-system)
+    - [Prompts](architecture.md#4-prompts)
+    - [Knowledge](architecture.md#5-knowledge)
+    - [Instruments](architecture.md#6-instruments)
+    - [Extensions](architecture.md#7-extensions)
+  - [Implementation Details](architecture.md#implementation-details)
   - [Customization](architecture.md#customization)
-    - [Custom Prompts](architecture.md#custom-prompts)
-      - [Changing the System Prompt Folder](architecture.md#changing-the-system-prompt-folder)
-    - [AgentConfig](architecture.md#agentconfig)
-    - [Adding Tools](architecture.md#adding-tools)
-    - [Adding Instruments](architecture.md#adding-instruments)
-    - [Adding Extensions](architecture.md#adding-extensions)
-- [Contributing to Agent Zero](contribution.md)
+- [Contributing](contribution.md)
   - [Getting Started](contribution.md#getting-started)
   - [Making Changes](contribution.md#making-changes)
   - [Submitting a Pull Request](contribution.md#submitting-a-pull-request)
   - [Documentation Stack](contribution.md#documentation-stack)
-- [FAQ and Troubleshooting](troubleshooting.md)
+- [Troubleshooting and FAQ](troubleshooting.md)
   - [Frequently Asked Questions](troubleshooting.md#frequently-asked-questions)
   - [Troubleshooting](troubleshooting.md#troubleshooting)

docs/architecture.md

@@ -1,199 +1,321 @@
 # Architecture Overview
-Agent Zero is built on a flexible and modular architecture designed for extensibility and customization. This section outlines the key components and the interactions between them. This simplified diagram illustrates the hierarchical relationship between agents and their interaction with tools, extensions, instruments, prompts, memory and knowledge base.
+Agent Zero is built on a flexible and modular architecture designed for extensibility and customization. This section outlines the key components and the interactions between them.
 
-![Agent Zero Architecture](res/arch-01.svg)
-
-The user or Agent 0 is at the top of the hierarchy, delegating tasks to subordinate agents, which can further delegate to other agents.  Each agent can utilize tools and access the shared assets (prompts, memory, knowledge, extensions and instruments) to perform its tasks.
+## System Architecture
+This simplified diagram illustrates the hierarchical relationship between agents and their interaction with tools, extensions, instruments, prompts, memory and knowledge base.
 
-## Core Components
-Agent Zero's architecture revolves around the following key components:
+![Agent Zero Architecture](res/arch-01.svg)
 
-1. **Agents:** The core actors within the framework. Agents receive instructions, reason, make decisions, and utilize tools to achieve their objectives. Agents operate within a hierarchical structure, with superior agents delegating tasks to subordinate agents.
+The user or Agent 0 is at the top of the hierarchy, delegating tasks to subordinate agents, which can further delegate to other agents. Each agent can utilize tools and access the shared assets (prompts, memory, knowledge, extensions and instruments) to perform its tasks.
 
-2. **Tools:** Tools are functionalities that agents can leverage. These can include anything from web search and code execution to interacting with APIs or controlling external software. Agent Zero provides a mechanism for defining and integrating both built-in and custom tools.
+## Runtime Architecture
+Agent Zero's runtime architecture is built around Docker containers:
 
-3. **Memory:** Agent Zero has persistent, long-term memory to store past experiences, knowledge, and information. This memory is used to inform decision-making and improve performance over time. Learn more in [Memory System](#memory-system)
+1. **Host System**:
+   - Requires only Docker and a web browser
+   - Runs Docker Desktop or Docker Engine
+   - Handles container orchestration
 
-4. **Prompts:** Guide agent's behavior and communication. The system and tools prompts defines the agent's overall role and objectives, while message prompts structure the interaction and flow of information and memory.
+2. **Runtime Container**:
+   - Houses the complete Agent Zero framework
+   - Manages the Web UI and API endpoints
+   - Handles all core functionalities including code execution
+   - Provides a standardized environment across all platforms
 
-5. **Knowledge:** Refers to the user-provided information and data that agents can leverage. This can include documents, databases, or any other relevant resources. Agents can retrieve and utilize this knowledge to answer questions, make decisions, and perform RAG-augmented tasks.
+This architecture ensures:
+- Consistent environment across platforms
+- Simplified deployment and updates
+- Enhanced security through containerization
+- Reduced dependency requirements on host systems
+- Flexible deployment options for advanced users
 
-6. **Instruments:** Instruments provide a way to add custom functionalities to Agent Zero. They can modify agent behavior introducing new procedures, function calls, or scripts to integrate with other systems. Instruments scripts are run inside the Docker Container.
+> [!NOTE]
+> The legacy approach of running Agent Zero directly on the host system (using Python, Conda, etc.) 
+> is still possible but requires Remote Function Calling (RFC) configuration through the Settings 
+> page. See [Full Binaries Installation](installation.md#in-depth-guide-for-full-binaries-installation) 
+> for detailed instructions.
 
-7. **Extensions:** Extensions are logical components that can be added to Agent Zero to enhance its capabilities. Extensions can include new message loops, custom memory management rules, or even more.
+## Core Components
+Agent Zero's architecture revolves around the following key components:
 
-8. **Docker Container:** Agent Zero execute code commands in a Docker container, which provides isolation and security. This ensures that agents can safely and securely interact with tools, especially when running code.
+### 1. Agents
+The core actors within the framework. Agents receive instructions, reason, make decisions, and utilize tools to achieve their objectives. Agents operate within a hierarchical structure, with superior agents delegating tasks to subordinate agents.
 
-## Agent Hierarchy and Communication
+#### Agent Hierarchy and Communication
 Agent Zero employs a hierarchical agent structure, where a top-level agent (often the user) can delegate tasks to subordinate agents. This hierarchy allows for the efficient breakdown of complex tasks into smaller, more manageable sub-tasks.
 
-Communication flows between agents through messages, which are structured according to the prompt templates.  These messages typically include:
+Communication flows between agents through messages, which are structured according to the prompt templates. These messages typically include:
 
 | Argument | Description |
 | --- | --- |
-| `Thoughts:` | The agent's Chain of Thought and planning process. |
-| `Tool name:` | The specific tool used by the agent. |
-| `Responses or queries:` | Results, feedback or queries from tools or other agents. |
+| `Thoughts:` | The agent's Chain of Thought and planning process |
+| `Tool name:` | The specific tool used by the agent |
+| `Responses or queries:` | Results, feedback or queries from tools or other agents |
 
-## Interaction Flow
+#### Interaction Flow
 A typical interaction flow within Agent Zero might look like this:
 
 ![Interaction Flow](res/flow-01.svg)
 
-1.  The user provides an instruction to Agent 0.
-2.  Agent 0 initializes VectorDB and access memory.
-3.  Agent 0 analyzes the instruction and formulates a plan using `thoughts` argument, possibly involving the use of tools or the creation of sub-agents.
-4.  If necessary, Agent 0 delegates sub-tasks to subordinate agents.
-5.  Agents use tools to perform actions, both providing arguments and responses or queries.
-6.  Agents communicate results and feedback back up the hierarchy.
-7.  Agent 0 provides the final response to the user.
+1. The user provides an instruction to Agent 0
+2. Agent 0 initializes VectorDB and access memory
+3. Agent 0 analyzes the instruction and formulates a plan using `thoughts` argument, possibly involving the use of tools or the creation of sub-agents
+4. If necessary, Agent 0 delegates sub-tasks to subordinate agents
+5. Agents use tools to perform actions, both providing arguments and responses or queries
+6. Agents communicate results and feedback back up the hierarchy
+7. Agent 0 provides the final response to the user
 
-## Memory System
-The memory system is a critical component of Agent Zero, enabling the agent to learn and adapt from past interactions. It operates on a hybrid model where part of the memory is managed automatically by the framework while users can also manually input and extract information.
-- **Memory Loading**: At the start of each session, relevant memories are automatically loaded and injected into the system prompt, allowing the agent to utilize past interactions effectively.
-- **Memory Structure**: The memory is categorized into four distinct areas:
-  - **Storage and retrieval** of user-provided information (e.g., names, API keys).
-  - **Fragments**: Contains pieces of information from previous conversations, updated automatically.
-  - **Solutions**: Stores successful solutions from past interactions for future reference.
-  - **Metadata**: Each memory entry includes metadata (IDs, timestamps), enabling efficient filtering and searching based on specific criteria.
+### 2. Tools
+Tools are functionalities that agents can leverage. These can include anything from web search and code execution to interacting with APIs or controlling external software. Agent Zero provides a mechanism for defining and integrating both built-in and custom tools.
 
-## Tools
-**Built-in Tools:** Agent Zero comes with a set of built-in tools, including web search and code execution. These tools are general-purpose and designed to help agents perform tasks efficiently:
+#### Built-in Tools
+Agent Zero comes with a set of built-in tools designed to help agents perform tasks efficiently:
 
 | Tool | Function |
 | --- | --- |
-| call_subordinate | Allows agents to delegate tasks to subordinate agents. |
-| code_execution_tool | Allows agents to execute Python, Node.js, and Shell code in the terminal of the Docker container. |
-| knowledge_tool | Enables agents to retrieve information from memory,  knowledge base or online external sources. |
-| response_tool | Allows agents to output a response. |
-| memory_tool | Enables agents to save, load, delete and forget information from memory. |
-| webpage_content_tool | Enables agents to fetch and analyze the text content of webpages. |
+| call_subordinate | Allows agents to delegate tasks to subordinate agents |
+| code_execution_tool | Allows agents to execute Python, Node.js, and Shell code in the terminal of the Docker container |
+| knowledge_tool | Enables agents to retrieve information from memory, knowledge base or online external sources |
+| response_tool | Allows agents to output a response |
+| memory_tool | Enables agents to save, load, delete and forget information from memory |
+| webpage_content_tool | Enables agents to fetch and analyze the text content of webpages |
 
-- **Knowledge Tool:** The `knowledge_tool` uses DuckDuckGo and Perplexity APIs to search the web and retrieve information. It can also search the local knowledge base and memory for relevant information. The tool returns a summary of the information, which can be used by the agent to make decisions or answer questions.
+#### Knowledge Tool
+The `knowledge_tool` uses SearXNG to search the web and retrieve information. It can also search the local knowledge base and memory for relevant information. The tool returns a summary of the information, which can be used by the agent to make decisions or answer questions.
 
-> [!TIP]
-> The Perplexity API key is the only service recommended for a full experience of 
-> Agent Zero, but you can use DuckDuckGo by leaving the Perplexity API key value 
-> empty. DuckDuckGo usage in Agent Zero is free of charge but has its rate limits.
-  
-> [!NOTE]  
-> It's important to note that the DuckDuckGo API is not as powerful as Perplexity 
-> and may not return accurate or relevant results for some queries. The Perplexity 
-> API is yet to be replaced with an open-source alternative.
+##### SearXNG Integration
+Agent Zero has integrated SearXNG as its primary search tool, replacing the previous knowledge tools (Perplexity and DuckDuckGo). This integration enhances the agent's ability to retrieve information while ensuring user privacy and customization.
+
+- Privacy-Focused Search
+SearXNG is an open-source metasearch engine that allows users to search multiple sources without tracking their queries. This integration ensures that user data remains private and secure while accessing a wide range of information.
 
-- **Custom Tools:** Users can create custom tools to extend Agent Zero's capabilities. Custom tools can be integrated into the framework by defining a tool specification, which includes the tool's prompt to be placed in `/prompts/$FOLDERNAME/agent.system.tool.$TOOLNAME.md`, as further detailed [here](#adding-tools).
+- Enhanced Search Capabilities
+The integration provides access to various types of content, including images, videos, and news articles, allowing users to gather comprehensive information on any topic.
 
-- **Tools vs. Instruments:** Tools are always present in system prompt, so you should keep them to minimum. To save yourself some tokens, use the [Instruments module](#adding-instruments) to call custom scripts or functions.
+- Fallback Mechanism
+In cases where SearXNG might not return satisfactory results, Agent Zero can be configured to fall back on other sources or methods, ensuring that users always have access to information.
 
-## Instruments
-- **Instruments:** Instruments allows you to add predefined actions or workflows to Agent Zero without adding to the token count of the system prompt. You can have unlimited amount of instruments, they are stored in long-term memory of Agent Zero, and recalled when needed. To create Instruments, see [Adding Instruments](#adding-instruments).
+> [!NOTE]
+> The Knowledge Tool is designed to work seamlessly with both online searches through 
+> SearXNG and local knowledge base queries, providing a comprehensive information 
+> retrieval system.
 
-## Knowledge
-- **Custom Knowledge:** Users can add custom knowledge files to the `/knowledge/custom/main` directory. Agent Zero will automatically import these files, expanding its knowledge base. Supported file formats include `.txt`, `.pdf`, `.csv`, `.html`, `.json`, and `.md`. The list of supported file formats is yet to be expanded.
-- **Knowledge Base:** PDFs, databases, books, code documentation, and other documents can be added to the knowledge base. Agent Zero uses this information to answer questions and make decisions. The `/docs` folder, containing Agent Zero's documentation stack, is automatically added to the knowledge base.
+#### Custom Tools
+Users can create custom tools to extend Agent Zero's capabilities. Custom tools can be integrated into the framework by defining a tool specification, which includes the tool's prompt to be placed in `/prompts/$FOLDERNAME/agent.system.tool.$TOOLNAME.md`, as detailed in [Adding Tools](#adding-tools).
 
-## Prompts
-The `prompts` directory contains various Markdown files that control agent behavior and communication. The most important file is `agent.system.main.md`, which acts as a central hub, referencing other prompt files.  
+> [!NOTE]
+> Tools are always present in system prompt, so you should keep them to minimum. 
+> To save yourself some tokens, use the [Instruments module](#adding-instruments) 
+> to call custom scripts or functions.
 
-**Key Prompt Files:**
+### 3. Memory System
+The memory system is a critical component of Agent Zero, enabling the agent to learn and adapt from past interactions. It operates on a hybrid model where part of the memory is managed automatically by the framework while users can also manually input and extract information.
+
+#### Memory Structure
+The memory is categorized into four distinct areas:
+- **Storage and retrieval** of user-provided information (e.g., names, API keys)
+- **Fragments**: Contains pieces of information from previous conversations, updated automatically
+- **Solutions**: Stores successful solutions from past interactions for future reference
+- **Metadata**: Each memory entry includes metadata (IDs, timestamps), enabling efficient filtering and searching based on specific criteria
+
+#### Messages History and Summarization
+Agent Zero implements a sophisticated message history and summarization system that helps maintain context while optimizing memory usage:
+
+- **Message Summaries**: Individual messages are summarized using a structured JSON format that captures key information while reducing token usage
+- **Dynamic Compression**: The system employs an intelligent compression strategy:
+  - Recent messages remain in their original form for immediate context
+  - Older messages are gradually compressed into more concise summaries
+  - Multiple compression levels allow for efficient context window usage
+  - Original messages are preserved separately from summaries
+- **Dual-Access Memory**: The system maintains two parallel streams of information:
+  - Compressed summaries in the context window for quick reference
+  - Original messages stored separately for detailed recall when needed
+- **Context Window Optimization**: 
+  - Acts as a near-infinite short-term memory for single conversations
+  - Automatically balances detail level based on message age and importance
+  - Maintains searchable indexes for efficient information retrieval
+  - Dynamically adjusts compression ratios based on available space
+- **Bulk and Topic Summarization**:
+  - Groups related messages into thematic chunks for better organization
+  - Generates concise summaries of multiple messages while preserving key context
+  - Enables efficient navigation of long conversation histories
+  - Maintains semantic connections between related topics
+
+### 4. Prompts
+The `prompts` directory contains various Markdown files that control agent behavior and communication. The most important file is `agent.system.main.md`, which acts as a central hub, referencing other prompt files.
+
+#### Core Prompt Files
 | Prompt File | Description |
 |---|---|
-| agent.system.main.role.md | Defines the agent's overall role. |
-| agent.system.main.communication.md | Specifies how the agent should communicate. |
-| agent.system.main.solving.md | Describes the agent's approach to tasks. |
-| agent.system.main.tips.md | Provides additional tips or guidance to the agent. |
-| agent.system.tools.md | Organizes and calls the individual tool prompt files. |
-| agent.system.tool.*.md | Individual tool prompt files (with * as the tool name). |
+| agent.system.main.role.md | Defines the agent's overall role and capabilities |
+| agent.system.main.communication.md | Specifies how the agent should communicate |
+| agent.system.main.solving.md | Describes the agent's approach to tasks |
+| agent.system.main.tips.md | Provides additional tips or guidance |
+| agent.system.main.behaviour.md | Controls dynamic behavior adjustments and rules |
+| agent.system.main.environment.md | Defines the runtime environment context |
+| agent.system.tools.md | Organizes and calls the individual tool prompt files |
+| agent.system.tool.*.md | Individual tool prompt files |
+
+#### Prompt Organization
+- **Default Prompts**: Located in `prompts/default/`, serve as the base configuration
+- **Custom Prompts**: Can be placed in custom subdirectories (e.g., `prompts/my-custom/`)
+- **Behavior Files**: Stored in memory as `behaviour.md`, containing dynamic rules
+- **Tool Prompts**: Organized in tool-specific files for modularity
+
+#### Dynamic Behavior System
+- **Behavior Adjustment**: 
+  - Agents can modify their behavior in real-time based on user instructions
+  - Behavior changes are automatically integrated into the system prompt
+  - Behavioral rules are merged intelligently, avoiding duplicates and conflicts
+
+- **Behavior Management Components**:
+  - `behaviour_adjustment.py`: Core tool for updating agent behavior
+  - `_20_behaviour_prompt.py`: Extension that injects behavior rules into system prompt
+  - Custom rules stored in the agent's memory directory as `behaviour.md`
+
+- **Behavior Update Process**:
+  1. User requests behavior changes (e.g., "respond in UK English")
+  2. System identifies behavioral instructions in conversation
+  3. New rules are merged with existing ruleset
+  4. Updated behavior is immediately applied
+
+![Behavior Adjustment](res/ui-behavior-change-chat.png)
+
+- **Integration with System Prompt**:
+  - Behavior rules are injected at the start of the system prompt
+  - Rules are formatted in a structured markdown format
+  - Changes are applied without disrupting other components
+  - Maintains separation between core functionality and behavioral rules
 
 > [!NOTE]  
-> You can customize any of these files.  Agent Zero will use the files in your custom `prompts_subdir` 
+> You can customize any of these files. Agent Zero will use the files in your custom `prompts_subdir` 
 > if they exist, otherwise, it will fall back to the files in `prompts/default`.
 
-## Extensions
-- Extensions are a powerful feature of Agent Zero, designed to keep the main codebase clean and organized while allowing for greater flexibility and modularity. Here’s a detailed exploration of the extensions feature:
-### Structure of Extensions
-Extensions can be found in `python/extensions` directory.
-- **Folder Organization**: The extensions are stored in a designated subfolder within the Python directory. This includes various subfolders that correspond to different aspects of the agent's message loop.
-- **Execution Order**: Files within these subfolders are executed in alphabetical order, ensuring predictable behavior when multiple extensions are utilized.
-### Types of Default Extensions
-- **Message Loop Prompts**: These extensions handle the construction of system messages and maintain message history, ensuring that the agent has access to relevant context during interactions.
-- **Memory Management**: Extensions can also manage memory recall and solution memorization, allowing for dynamic updates based on user interactions.
-- **Custom Extensions**: Users can create custom extensions to add new functionalities or modify existing ones. See [Adding Extensions](#adding-extensions) for more details.
-
-## Key Files
-| File | Description |
-| --- | --- |
-| `agent.py` | Contains the core logic for the `Agent`, `AgentConfig`, and messages classes, which defines the `prompts_subdir`, rate limits for models, and more, though `AgentConfig` class must be edited through `initialize.py` file. |
-| `example.env` | Contains environment variables for configuring API keys and other settings of Agent Zero. See more in [Installation](installation.md#5-configure-agent-zero) |
-| `initialize.py` | Defines Agent Zero's core configuration, including model choices and other critical settings. This is the central point for customizing the framework's behavior. See [Choosing Your LLMs](installation.md#choosing-your-llms) for more details. |
-| `models.py` | Defines the `get_provider_chat` or `..._embedding` functions, which specifies the model provider, model name, and other parameters for adding support for new models or custom models. |
-| `requirements.txt` | Lists the dependencies used by pip to install the necessary packages when you setup Agent Zero. |
-| `run_cli.py` | Starts the Agent Zero CLI. |
-| `run_ui.py` | Starts the Agent Zero Web UI. |
-
-## Directory Structure
+> [!TIP]
+> The behavior system allows for dynamic adjustments without modifying the base prompt files.
+> Changes made through behavior rules persist across sessions while maintaining the core functionality.
+
+### 5. Knowledge
+Knowledge refers to the user-provided information and data that agents can leverage:
+
+- **Custom Knowledge**: Add files to `/knowledge/custom/main` directory manually or through the "Import Knowledge" button in the UI
+  - Supported formats: `.txt`, `.pdf`, `.csv`, `.html`, `.json`, `.md`
+  - Automatically imported and indexed
+  - Expandable format support
+
+- **Knowledge Base**: 
+  - Can include PDFs, databases, books, documentation
+  - `/docs` folder automatically added
+  - Used for answering questions and decision-making
+  - Supports RAG-augmented tasks
+
+### 6. Instruments
+Instruments provide a way to add custom functionalities to Agent Zero without adding to the token count of the system prompt:
+- Stored in long-term memory of Agent Zero
+- Unlimited number of instruments available
+- Recalled when needed by the agent
+- Can modify agent behavior by introducing new procedures
+- Function calls or scripts to integrate with other systems
+- Scripts are run inside the Docker Container
+- Implementation details in [Adding Instruments](#adding-instruments)
+
+### 7. Extensions
+Extensions are a powerful feature of Agent Zero, designed to keep the main codebase clean and organized while allowing for greater flexibility and modularity.
+
+#### Structure
+Extensions can be found in `python/extensions` directory:
+- **Folder Organization**: Extensions are stored in designated subfolders corresponding to different aspects of the agent's message loop
+- **Execution Order**: Files are executed in alphabetical order for predictable behavior
+- **Naming Convention**: Files start with numbers to control execution order
+- **Modularity**: Each extension focuses on a specific functionality
+
+#### Types
+- **Message Loop Prompts**: Handle system messages and history construction
+- **Memory Management**: Handle recall and solution memorization
+- **Custom Extensions**: Add new functionalities (see [Adding Extensions](#adding-extensions))
+- **Behavior Management**: Handle dynamic behavior adjustments
+- **System Integration**: Manage interaction with external systems
+
+## Implementation Details
+
+### Directory Structure
 | Directory | Description |
 | --- | --- |
-| `/bundle` | Contains the scripts for bundling the project into a single exe file for easy distribution. |
-| `/docker` | Dockerfiles and related files for building Docker image |
-| `/docs` | Quickstart and installation guide |
-| `/instruments` | Instruments for interacting with the environment |
-| `/knowledge` | Knowledge base for storing and retrieving information |
-| `/logs` | HTML chat log files |
-| `/memory` | Memory storage for storing and retrieving information |
-| `/prompts` | System and tools prompts folders |
-| `/python` | Python code for the main system and tools |
-| `/python/extensions` | Extensions for the main system |
-| `/tests` | Unit tests for the project |
-| `/tmp/chats` | Chats files storage directory |
-| `/webui` | Web UI |
-| `/work_dir` | Working directory for the Agent |
-
-# Customization
+| `/docker` | Docker-related files for runtime container |
+| `/docs` | Documentation files and guides |
+| `/instruments` | Custom scripts and tools for runtime environment |
+| `/knowledge` | Knowledge base storage |
+| `/logs` | HTML CLI-style chat logs |
+| `/memory` | Persistent agent memory storage |
+| `/prompts` | System and tool prompts |
+| `/python` | Core Python codebase: |
+|   `/api` | API endpoints and interfaces |
+|   `/extensions` | Modular extensions |
+|   `/helpers` | Utility functions |
+|   `/tools` | Tool implementations |
+| `/tmp` | Temporary runtime data |
+| `/webui` | Web interface components: |
+|   `/css` | Stylesheets |
+|   `/js` | JavaScript modules |
+|   `/public` | Static assets |
+| `/work_dir` | Working directory |
+
+### Key Files
+| File | Description |
+| --- | --- |
+| `.env` | Environment configuration |
+| `agent.py` | Core agent implementation |
+| `example.env` | Configuration template |
+| `initialize.py` | Framework initialization |
+| `models.py` | Model providers and configs |
+| `preload.py` | Pre-initialization routines |
+| `prepare.py` | Environment preparation |
+| `requirements.txt` | Python dependencies |
+| `run_cli.py` | CLI launcher |
+| `run_ui.py` | Web UI launcher |
+
+> [!NOTE]
+> When using the Docker runtime container, these directories are mounted 
+> within the `/a0` volume for data persistence until the container is restarted or deleted.
+
+## Customization
 Agent Zero's strength lies in its flexibility. This section details how to customize various aspects of the framework, tailoring it to your specific needs and preferences.
 
-## Custom Prompts
-### Changing the System Prompt Folder
-1. Create a new directory inside the `prompts` directory (e.g., `prompts/my-custom-prompts`).
-2. When copying the contents of the `prompts/default` directory into your new directory, take into account that Agent Zero will merge the contents of the `default` directory with the contents of your custom directory. This means that you can copy only the files you want to modify, and the rest will be taken from the `default` directory.
-3. Modify the prompts in your custom directory as needed.
-4. In `initialize.py`, update the `prompts_subdir` parameter in `AgentConfig` to point to your custom directory:
-   ```python
-   config = AgentConfig(..., prompts_subdir="my-prompts-folder", ...)
-   ```
-
-## AgentConfig
-The `AgentConfig` class is present in both `agent.py` and `initialize.py` and provides further customization options. You must edit `AgentConfig` class through `initialize.py` file. Here are some of the key parameters you can configure:
-
-- `prompts_subdir`: Specifies the directory containing your custom prompts.  This allows you to create and manage different sets of prompts for different use cases.  (See *Prompt Customization* below).
-
-- `knowledge_subdirs`: Defines the directories where Agent Zero searches for knowledge files.
-
-- **Rate Limiting:** Control API usage and prevent rate limit errors by setting `rate_limit_seconds` and `rate_limit_requests`.
-
-- **Docker and SSH:** Configure Docker and SSH settings for code execution, if needed. If you need to configure SSH to run on another machine, such as a remote VM, see more in 
-
-## Adding Tools
-While good prompting can often achieve the desired behavior, sometimes custom tools are necessary.
-
-1. Create a new file named `agent.system.tool.$TOOL_NAME.md` inside your `prompts/$SUBDIR` directory. This file will contain the prompt for your custom tool.
-2. Open `agent.system.tools.md` and add a reference to your new tool prompt.
-3. If your tool requires specific code or external API calls, create a Python file for it in the `python/tools` directory, implementing the `Tool` base class.
-
-## Adding Instruments
-To create a new Instrument, follow these steps:
-1. Create a new folder with the name of your instrument (without spaces) inside `instruments/custom`.
-2. Inside this folder, create a `.md` file with the description of the instrument and a `.sh` script (or other executable) with the actual implementation. The `.md` file acts as the interface for the Agent to interact with the Instrument, and the agent will call the `.sh` with the given user arguments. The agent will parse the `.md` file, using the Instrument's name, description, and arguments described in it.
-3. The agent will automatically detect and use your custom instruments.
-
-## Adding Extensions
-To create a new extension, follow these steps:
-1. Create a new Python file in the appropriate subfolder within the `python/extensions` directory.
-2. Implement the desired functionality within the file, following the existing structure and naming conventions, that implies following the alphabetical order of execution of the extensions in the subfolder.
-3. Your desired extension's name has to start with a number to ensure it is executed before or after an already existing extension based on your needs.
-4. Ensure that the extension is compatible with the main system and does not introduce any conflicts or errors.
+### AgentConfig
+The `AgentConfig` class in `initialize.py` provides various customization options:
+
+- `prompts_subdir`: Specifies the directory containing your custom prompts
+- `knowledge_subdirs`: Defines the directories where Agent Zero searches for knowledge files
+- **Rate Limiting:** Control API usage with `rate_limit_seconds` and `rate_limit_requests`
+- **Docker and SSH:** Configure execution environment settings
+
+### Adding Custom Components
+
+#### Custom Prompts
+1. Create directory in `prompts/` (e.g., `my-custom-prompts`)
+2. Copy and modify needed files from `prompts/default/`
+3. Agent Zero will merge your custom files with the default ones
+4. Select your custom prompts in the Settings page
+
+#### Adding Instruments
+1. Create folder in `instruments/custom` (no spaces in name)
+2. Add `.md` description file for the interface
+3. Add `.sh` script (or other executable) for implementation
+4. The agent will automatically detect and use the instrument
+
+#### Adding Tools
+1. Create `agent.system.tool.$TOOL_NAME.md` in `prompts/$SUBDIR`
+2. Add reference in `agent.system.tools.md`
+3. If needed, implement tool class in `python/tools` using `Tool` base class
+4. Follow existing patterns for consistency
+
+#### Adding Extensions
+1. Create Python file in appropriate `python/extensions` subfolder
+2. Follow naming convention for execution order (start with number)
+3. Implement functionality following existing patterns
+4. Ensure compatibility with main system
+5. Test thoroughly before deployment
 
 > [!NOTE]  
-> If you believe your custom tool, instrument or extension could bring value to the community, consider contributing 
-> it to the main repository by making a pull request. This will make it available for others to use and benefit from your work. 
+> Consider contributing valuable custom components to the main repository.
 > See [Contributing](contribution.md) for more information.

docs/contribution.md

@@ -11,7 +11,6 @@ Contributions to improve Agent Zero are very welcome!  This guide outlines how t
 ## Making Changes
 
 * **Code Style:** Follow the existing code style. Agent Zero generally follows PEP 8 conventions.
-* **Testing:** Write unit tests for new features. Agent Zero uses the `pytest` framework. Ensure your changes pass all existing and new tests.
 * **Documentation:**  Update the documentation if your changes affect user-facing functionality. The documentation is written in Markdown.
 * **Commit Messages:**  Write clear and concise commit messages that explain the purpose of your changes.
 
@@ -19,8 +18,7 @@ Contributions to improve Agent Zero are very welcome!  This guide outlines how t
 
 1. **Push Your Branch:** Push your branch to your forked repository on GitHub.
 2. **Create a Pull Request:** Create a pull request from your branch to the appropriate branch in the main Agent Zero repository.
-   * **For new features, refactoring, or significant changes:** Target the `testing` branch.
-   * **For bug fixes and patches:** Target the `development` branch.
+   * Target the `development` branch.
 3. **Provide Details:** In your pull request description, clearly explain the purpose and scope of your changes. Include relevant context, test results, and any other information that might be helpful for reviewers.
 4. **Address Feedback:**  Be responsive to feedback from the community. We love changes, but we also love to discuss them!
 

docs/installation.md

@@ -1,121 +1,40 @@
-# Installation guide for Windows, macOS and Linux
+# Users installation guide for Windows, macOS and Linux
 
-[![Video](res/setup/thumb_play.png)](https://youtu.be/8H7mFsvxKYQ)
-
-The following guide provides both quick start instructions for the full installation of Agent Zero on various operating systems and in-depth guides for Windows and macOS with screenshots.
-
-## You were looking for this? [How to update Agent Zero](#how-to-update-agent-zero)
-
-<details>
-<summary><h2>Windows Quick Start</h2></summary>
-
-1. **Install Anaconda or Miniconda:** Download and install the appropriate version for your system from [here](https://docs.anaconda.com/anaconda/install/). Miniconda is recommended for a minimal installation.
-2. **Create an Environment:** Open Anaconda Navigator (or use the `conda` command), create an environment named `agent-zero`, and select Python 3.12.
-3. **Install Docker Desktop:** Download and install Docker Desktop from [here](https://www.docker.com/products/docker-desktop/).
-4. **Download Agent Zero:** Download the latest release zip from the [GitHub releases page](https://github.com/frdel/agent-zero/releases) and extract it.
-5. **Configure API Keys:** Duplicate `example.env`, rename it to `.env`, and add your API keys.
-6. **Install Requirements:** Activate your `agent-zero` environment, open a terminal in the Agent Zero directory, and run: `pip install -r requirements.txt`
-7. **Run Agent Zero (Web UI):** Execute `python run_ui.py` in your terminal.
-8. **Access the Web UI:** Open the URL displayed in your browser.
-
-</details>
-
-<details>
-<summary><h2>macOS Quick Start</h2></summary>
-
-1. **Install Miniconda:** Download the pkg installer from [here](https://docs.anaconda.com/miniconda/#miniconda-latest-installer-links) and follow the instructions.
-2. **Install Docker Desktop:** Download the dmg image from [here](https://www.docker.com/products/docker-desktop/), drag the Docker application to your Applications folder, and create a Docker Hub account.
-3. **Download Agent Zero:** Download the latest release zip from the [GitHub releases page](https://github.com/frdel/agent-zero/releases) and extract it.
-4. **Open Terminal:** Navigate to the Agent Zero directory.
-5. **Create Conda Environment:** Run: `conda create -n a0 python=3.12 -y`
-6. **Activate Environment:** Run: `conda activate a0`
-7. **Install Requirements:** Run: `pip install -r requirements.txt`
-8. **Configure API Keys:** Create a `.env` file and add your keys.
-9. **Run Agent Zero (Web UI):** Run: `python run_ui.py`
-10. **Access the Web UI:** Open the displayed URL.
-
-> [!IMPORTANT]  
-> **Important macOS 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.
-
-![docker socket macOS](res/setup/macsocket.png)
-
-</details>
-
-<details>
-<summary><h2>Linux Quick Start</h1></summary>
-
-1. **Install Python and Pip:** Use your distribution's package manager (e.g., `apt`, `yum`, `dnf`) to install Python 3.12 or higher and pip. On Debian/Ubuntu systems, you would typically use:
-   ```bash
-   sudo apt-get update
-   sudo apt-get install python3.12 python3-pip
-   ```
-2. **Install Miniconda:** Download the appropriate installer for your Linux distribution from [here](https://docs.anaconda.com/miniconda/#miniconda-latest-installer-links) and follow the instructions.
-3. **Install Docker:** Install Docker Desktop or Docker CE using your distribution's package manager. Make sure the Docker service is running: `sudo systemctl start docker`
-4. **Download Agent Zero:** Download the latest release zip from the [GitHub releases page](https://github.com/frdel/agent-zero/releases) and extract it.
-5. **Open Terminal and Navigate:** Open your terminal and navigate to the extracted Agent Zero folder using the `cd` command.
-6. **Create and Activate Conda Environment:**
-   ```bash
-   conda create -n a0 python=3.12 -y
-   conda activate a0
-   ```
-7. **Install Requirements:** `pip install -r requirements.txt`
-8. **Configure API Keys:** Create a `.env` file in the project root and add your API keys. You can copy the `example.env` file and rename it to `.env`.
-9. **Run Agent Zero (Web UI):** `python run_ui.py`
-10. **Access the Web UI:** Open the URL displayed in your terminal.
-
-</details>
-
-# In-Depth Guide for Windows and macOS
-- Agent Zero is not an app. It's a framework. It's made to be customized, edited, enhanced. Therefore you need to install the necessary components to run it.
-- The following step by step instructions can be followed along with a video for this tutorial on how to make Agent Zero work on Windows and macOS that you find in the [top section](#installation-guide-for-windows-macos-and-linux) of the page.
-
-## Reminders:
-1. There's no need to install Python, Conda will manage that for you.
-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 simple video explanation for running Free and Local models is available [in this video](https://www.youtube.com/watch?v=sLMhLRHDIPY&t=80s).
-3. Visual Studio Code or any other code editor is not mandatory, but it makes it easier to navigate and edit files.
-4. Docker is not mandatory, but running Agent Zero without Docker is actually more complicated and can be very dangerous, so we will be covering the easier and recommended way - using Docker Desktop application.
-5. 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.
-
-## 1. Install Conda (miniconda)
-- Conda is a python environment manager, it will help you keep your projects and installations separated. Full Conda has many more features, but you only need "miniconda".
+[![Setup Guide](res/setup/thumb_setup.png)](https://www.youtube.com/watch?v=wWAqJpl3uQE)
 
-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".
-2. Based on your operating system, download the right installer of miniconda. For macOS select the version with "pkg" at the end.
+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).
 
-<img src="res/setup/image-1.png" alt="miniconda download win" width="500"/>
-<img src="res/setup/image-5.png" alt="miniconda download macos" width="500"/>
-<br><br>
-
-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.
-
-<img src="res/setup/image.png" alt="miniconda install" width="200"/>
-<img src="res/setup/image-2.png" alt="miniconda install" width="200"/>
-<img src="res/setup/image-3.png" alt="miniconda install" width="200"/>
-<img src="res/setup/image-4.png" alt="miniconda install" width="200"/>
-<br><br>
+### Maybe you're looking for this? 👉[How to update Agent Zero](#how-to-update-agent-zero)
 
-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.
+## Windows, macOS and Linux Setup Guide
 
-<img src="res/setup/image-6.png" alt="miniconda installed" height="100"/>
-<img src="res/setup/image-7.png" alt="miniconda installed" height="100"/>
-<br><br>
+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
 
-## 2. 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.
-- Running Agent Zero without Docker is possible, but more complicated and dangerous, I will not be covering that in this tutorial.
-- Docker has a desktop application with GUI for all major operating system, so I will be using that.
+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".
 
-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.
+1.2. Download the version for your operating system. For Windows users, the Intel/AMD version is the main download button.
 
 <img src="res/setup/image-8.png" alt="docker download" width="200"/>
 <br><br>
 
-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.
+> [!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.
 
 <img src="res/setup/image-9.png" alt="docker install" width="300"/>
 <img src="res/setup/image-10.png" alt="docker install" width="300"/>
@@ -123,112 +42,151 @@ The following guide provides both quick start instructions for the full installa
 <img src="res/setup/image-12.png" alt="docker install" width="300"/>
 <br><br>
 
-
-4. Once installed, you should see Docker Desktop application on your Windows/Mac machine. 
+1.4. Once installed, launch Docker Desktop: 
 
 <img src="res/setup/image-11.png" alt="docker installed" height="100"/>
 <img src="res/setup/image-13.png" alt="docker installed" height="100"/>
 <br><br>
 
-5. Create account in the application.
-No need to create images or containers, the framework will do that for you. However, this requires you 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.
+1.5. Create a Docker Hub account when prompted and sign in. This is required to pull the Agent Zero container image.
 
 > [!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.
+> **macOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings → 
+> Advanced, enable "Allow the default Docker socket to be used (requires password)."
 
 ![docker socket macOS](res/setup/macsocket.png)
 
-## 3. Download Agent Zero
-- You can clone the Agent Zero repository (https://github.com/frdel/agent-zero) from GitHub if you know how to use Git. In this tutorial I will just show how to download the files.
+2. **Run Agent Zero:**
 
-1. Go to the Agent Zero releases [here](https://github.com/frdel/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.
+2.1. Pull the Agent Zero Docker image:
+- Search for `frdel/agent-zero-run` in Docker Desktop
+- Click the `Pull` button
+- The image will be downloaded to your machine in a few minutes
+
+![docker pull](res/setup/1-docker-image-search.png)
+
+> [!TIP]
+> Alternatively, run the following command in your terminal:
+>
+> ```bash
+> docker pull frdel/agent-zero-run
+> ```
+
+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
+
+> [!TIP]
+> Choose a location that's easy to access and backup. All your Agent Zero data 
+> will be directly accessible in this directory.
 
-<img src="res/setup/image-14.png" alt="agent zero download" width="500"/>
-<br><br>
+2.3. Run the container:
+- In Docker Desktop, go back to the "Images" tab
+- Click the `Run` button next to the `frdel/agent-zero-run` image
+- Open the "Optional settings" menu
+- Set the port to `0` in the second "Host port" field (for automatic port assignment)
+- Under "Volumes", configure:
+  - Host path: Your chosen directory (e.g., `C:\agent-zero-data`)
+  - Container path: `/a0`
 
-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.
+![docker port mapping](res/setup/3-docker-port-mapping.png)
 
+- Click the `Run` button in the "Images" tab.
+- The container will start and show in the "Containers" tab
 
-## 4. 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.
+![docker containers](res/setup/4-docker-container-started.png)
 
-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.
+> [!TIP]
+> Alternatively, run the following command in your terminal:
+> ```bash
+> docker run -p $PORT:80 -v /path/to/your/data:/a0 frdel/agent-zero-run
+> ```
+> - Replace `$PORT` with the port you want to use (e.g., `50080`)
+> - Replace `/path/to/your/data` with your chosen directory path
 
-<img src="res/setup/image-15.png" alt="agent zero cd" height="100"/>
-<img src="res/setup/image-16.png" alt="agent zero cd" height="100"/>
-<br><br>
+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 `<PORT>:80`) or click the port right under the container ID as shown in the image below
 
-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
-~~~
+![docker logs](res/setup/5-docker-click-to-open.png)
 
-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.
+- Open `http://localhost:<PORT>` in your browser
+- The Web UI will open. Agent Zero is ready for configuration!
 
-<img src="res/setup/image-17.png" alt="conda env" height="200"/>
-<img src="res/setup/image-18.png" alt="conda env" height="200"/>
-<br><br>
+![docker ui](res/setup/6-docker-a0-running.png)
 
-> [!IMPORTANT]  
-> If you open a new terminal window, you will need to activate the environment with 
-> "conda activate a0" again for that window.
+> [!TIP]
+> You can also access the Web UI by clicking the ports right under the container ID in Docker Desktop.
 
-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.
+> [!NOTE]
+> 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.
 
-<img src="res/setup/image-19.png" alt="conda reqs" height="200"/>
-<br><br>
+3. Configure Agent Zero
+- Refer to the following sections for a full guide on how to configure Agent Zero.
 
-## 5. Configure Agent Zero
-- Now we can configure Agent Zero - select models, settings, API Keys etc.
-- I will leave the default configuration using OpenAI API and I will just provide my OpenAI API key in the **.env** file.
+## Settings Configuration
+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.
 
-1. Find the **"example.env"** file in your Agent Zero folder and edit the contents. I will put my OpenAI API key after **"API_KEY_OPENAI="**. If you have API keys for other service providers, add them as needed.
-2. Rename the **"example.env"** file to **".env"**. This is important, only this exact "**.env**" file name is valid.
+### Agent Configuration
+- **Prompts Subdirectory:** Choose the subdirectory within `/prompts` for agent behavior customization. The 'default' directory contains the standard prompts.
+- **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances.
+- **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding.
 
-<img src="res/setup/image-20.png" alt="conda reqs" height="200"/>
-<br><br>
+![settings](res/setup/settings/1-agentConfig.png)
 
-3. (Optional) Change models or setting in **"initialize.py"** file if needed as detailed [here](#choosing-your-llms).
+### Chat Model Settings
+- **Provider:** Select the chat model provider (e.g., Ollama)
+- **Model Name:** Choose the specific model (e.g., llama3.2)
+- **Temperature:** Adjust response randomness (0 for deterministic, higher values for more creative responses)
+- **Context Length:** Set the maximum token limit for context window
+- **Context Window Space:** Configure how much of the context window is dedicated to chat history
 
-## 6. Run Agent Zero
-- Setup done. It's time to test Agent Zero. Let's double check:
+![chat model settings](res/setup/settings/2-chat-model.png)
 
-1. Make sure you have the **"a0"** Conda environment still active in your current terminal window. You can see that on the left of each terminal line like **(a0)** or **(base)**. If not, activate again with **"conda activate a0"** command again.
-2. Make sure your terminal is looking into the Agent Zero folder. If not, navigate to it with **"cd"** command again with your path.
-3. Run the **Docker Desktop application** you installed and just leave it running in the background. No need to create images or containers, the framework will do that for you. However, this requires you to be signed in to the Docker Hub, so sign in in the Docker Desktop application, if you haven't already.
-4. Run the Agent Zero with Web UI:
-~~~
-python run_ui.py
-~~~
+### Utility Model Configuration
+- **Provider & Model:** Select a smaller, faster model for utility tasks like memory organization and summarization
+- **Temperature:** Adjust the determinism of utility responses
+
+### Embedding Model Settings
+- **Provider:** Choose the embedding model provider (e.g., OpenAI)
+- **Model Name:** Select the specific embedding model (e.g., text-embedding-3-small)
+
+### Speech to Text Options
+- **Model Size:** Choose the speech recognition model size
+- **Language Code:** Set the primary language for voice recognition
+- **Silence Settings:** Configure silence threshold, duration, and timeout parameters for voice input
+
+### API Keys
+- Configure API keys for various service providers directly within the Web UI
+- Click `Save` to confirm your settings
+
+### Authentication
+- **UI Login:** Set username for web interface access
+- **UI Password:** Configure password for web interface security
+- **Root Password:** Manage Docker container root password for SSH access
 
-<img src="res/setup/image-21.png" alt="run ui" height="110"/>
-<br><br>
+![settings](res/setup/settings/3-auth.png)
 
-5. Open the URL shown in terminal in your web browser. You should see the Agent Zero interface. The first time it needs to execute code, Docker image will be downloaded and deployed, this might take some time. Be patient when seeing "Initializing docker container agent-zero-exe for safe code execution...".
+### Development Settings
+- **RFC Parameters (local instances only):** configure URLs and ports for remote function calls between instances
+- **RFC Password:** Configure password for remote function calls
+Learn more about Remote Function Calls and their purpose [here](#7-configure-agent-zero-rfc).
 
-<img src="res/setup/image-22-1.png" alt="run ui" width="400"/>
-<img src="res/setup/image-23-1.png" alt="run ui" width="400"/>
-<br><br>
+> [!IMPORTANT]
+> Always keep your API keys and passwords secure.
 
 # Choosing Your LLMs
-The `initialize.py` file is the control center for selecting the Large Language Models (LLMs) that power Agent Zero.  You can choose different LLMs for different roles:
+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:
 
 | LLM Role | Description |
 | --- | --- |
@@ -237,13 +195,9 @@ The `initialize.py` file is the control center for selecting the Large Language
 | `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. |
 
 **How to Change:**
-1. Open `initialize.py`.
-2. Locate the lines where these LLMs are initialized (at the beginning of the file).
-3. Uncomment the line for the provider and model you want to use, and comment out the others.  For example, to use `gpt-4o-mini` for chat:
-   ```python
-   chat_llm = models.get_openai_chat(model_name="gpt-4o-mini", temperature=0)
-   ```
-4. Ensure only one model is uncommented for each LLM role.
+1. Open Settings page in the Web UI.
+2. Choose the provider for the LLM for each role (Chat model, Utility model, Embedding model) and write the model name.
+3. Click "Save" to apply the changes.
 
 ## Important Considerations
 
@@ -252,8 +206,6 @@ The `initialize.py` file is the control center for selecting the Large Language
 > requires clearing the `memory` folder to avoid errors, as the embeddings can't be 
 > mixed in the vector database. Note that this will DELETE ALL of Agent Zero's memory.
 
-- 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.
-
 ## Installing and Using Ollama (Local Models)
 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:
 
@@ -284,7 +236,20 @@ Visit the [Ollama model library](https://ollama.com/library) for a list of avail
 ollama pull <model-name>
 ```
 
-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`.
+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`.
+
+2. A CLI message should confirm the model download on your system
+
+#### Selecting your model within Agent Zero
+1. Once you've downloaded your model(s), you must select it in the Settings page of the GUI. 
+
+2. Within the Chat model, Utility model, or Embedding model section, choose Ollama as provider.
+
+3. Write your model code as expected by Ollama, in the format `llama3.2` or `qwen2.5:7b`
+
+4. Click `Save` to confirm your settings.
+
+![ollama](res/setup/settings/4-local-models.png)
 
 #### Managing your downloaded models
 Once you've downloaded some models, you might want to check which ones you have available or remove any you no longer need.
@@ -300,35 +265,293 @@ Once you've downloaded some models, you might want to check which ones you have
   ollama rm <model-name>
   ```
 
-# How to update Agent Zero
-To update Agent Zero to the latest version, follow these steps:
-- **Using Git/GitHub:** Pull the latest version of the Agent Zero repository with Git/GitHub. The custom knowledge, solutions, memory, and other data will get ignored by Git, 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.
-- **Backup LLM choices**: Before updating, make sure to save your customizations you've made to the first part of `def_initialize` function in the `initialize.py` file to choose your LLMs (highlighted section in below figure). This is important because the update process will overwrite these files with the default versions from the repository and can save you time rewriting all your LLMs choices.
 
-![Update initialize.py](res/setup/update-initialize.png)
+- 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.
 
-Beware of indentations when pasting the model selection code back into the `initialize.py` file after the update.
+## Using Agent Zero on your mobile device
+Agent Zero's Web UI is accessible from any device on your network through the Docker container:
+
+1. The Docker container automatically exposes the Web UI on all network interfaces
+2. Find the mapped port in Docker Desktop:
+   - Look under the container name (usually in the format `<PORT>:80`)
+   - For example, if you see `32771:80`, your port is `32771`
+3. Access the Web UI from any device using:
+   - Local access: `http://localhost:<PORT>`
+   - Network access: `http://<YOUR_COMPUTER_IP>:<PORT>`
+
+> [!TIP]
+> - Your computer's IP address is usually in the format `192.168.x.x` or `10.0.x.x`
+> - You can find your external IP address by running `ipconfig` (Windows) or `ifconfig` (Linux/Mac)
+> - The port is automatically assigned by Docker unless you specify one
+
+> [!NOTE]
+> If you're running Agent Zero directly on your system (legacy approach) instead of 
+> 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"`.
+
+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).
+
+### How to update Agent Zero
+
+1. **If you come from the previous version of Agent Zero (pre-0.7.1):**
+- Your data is safely stored across various directories and files inside the Agent Zero folder.
+- To update to the new Docker runtime version, you need to save the following files and directories:
+  - `/memory` - Agent's memory
+  - `/knowledge` - Custom knowledge base
+  - `/instruments` - Custom instruments and functions
+  - `/prompts` - Custom prompts files (if any has been created)
+  - `/work_dir` - Working directory
+  - `.env` - Your API keys
+  - `/tmp/settings.json` - Your Agent Zero settings
+- 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.
+- Reach for the folder where you saved your data and copy it to the new Agent Zero folder set during the installation process.
+- Agent Zero will automatically detect your saved data and use it across memory, knowledge, instruments, prompts and settings.
+
+> [!IMPORTANT]
+> Make sure to use the same embedding model you were using before, otherwise 
+> you will have to re-index all of Agent Zero's memory, therefore deleting all 
+> your custom knowledge and memory.
+
+> [!NOTE]
+> If you have issues loading your settings, you can try to delete the `/tmp/settings.json` 
+> file and let Agent Zero generate a new one.
+
+2. **Update Process (Docker Desktop)**
+- Go to Docker Desktop and stop the container from the "Containers" tab
+- Right-click and select "Remove" to remove the container
+- Go to "Images" tab and remove the `frdel/agent-zero-run` image
+
+![docker delete image](res/setup/docker-delete-image-1.png)
+
+- Search and pull the new image
+- Run the new container with the same volume settings as the old one
+
+> [!IMPORTANT]
+> Make sure to use the same volume mount path when running the new
+> container to preserve your data. The exact path depends on where you stored
+> your Agent Zero data directory (the chosen directory on your machine).
+
+> [!TIP]
+> Alternatively, run the following commands in your terminal:
+>
+> ```bash
+> # Stop the current container
+> docker stop agent-zero
+>
+> # Remove the container (data is safe in the folder)
+> docker rm agent-zero
+>
+> # Remove the old image
+> docker rmi frdel/agent-zero-run
+>
+> # Pull the latest image
+> docker pull frdel/agent-zero-run
+>
+> # Run new container with the same volume mount
+> docker run -p $PORT:80 -v /path/to/your/data:/a0 frdel/agent-zero-run
+> ```
+
+3. **Full Binaries**
+- Using Git/GitHub: Pull the latest version of the Agent Zero repository. 
+- 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.
 
-- **Manual Update:** Alternatively, you can manually download the latest version of Agent Zero from the [releases page](https://github.com/frdel/agent-zero/releases). The only folders that you must save to retain custom data are the following: `/memory`, `/knowledge`. If you have created custom `instruments` or `prompts` you must save their dirs as well.
+> [!WARNING]  
+> - If you update manually, beware: save your .env file with the API keys, and look for new dependencies in requirements.txt. 
+> - 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:
+> ```bash
+> pip install -r requirements.txt
+
+# In-Depth Guide for Full Binaries Installation
+- 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.
+- 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.
+
+[![Video](res/setup/thumb_play.png)](https://youtu.be/8H7mFsvxKYQ)
+
+## Reminders:
+1. There's no need to install Python, Conda will manage that for you.
+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).
+3. Visual Studio Code or any other code editor is not mandatory, but it makes it easier to navigate and edit files.
+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.
+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.
+6. Running Agent Zero without Docker makes the process more complicated and it's thought for developers and contributors.
 
 > [!IMPORTANT]  
-> If you update manually, beware: save your .env file with the API keys, and look 
-> for new dependencies in requirements.txt. If any changes are made in the updated 
-> version, you have to execute this command inside the a0 conda env after activating it:
-      
-      pip install -r requirements.txt
+> 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.
+>
+> For Debian/Ubuntu, just follow the macOS instructions, as they are the same.
+
+## 1. Install Conda (miniconda)
+- Conda is a Python environment manager, it will help you keep your projects and installations separated. 
+- 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.
 
-# How to create executable files for Agent Zero in Windows, macOS and Linux
-Two scripts allows you to easily create executable files for Windows, macOS and Linux, including all the necessary dependencies to run Agent Zero without the need for Python, Conda, or additional steps:
-1. **Navigate to Bundle folder:** Navigate to /agent-zero/bundle.
-2. **Run the script:** Run the bundling of Agent Zero by running `macos_bundle.sh` (macOS and Linux) or `windows_bundle.bat` (Windows) in your terminal window. The process usually takes about 2 to 5 minutes depending on the platform.
-3. **Edit your Files:** Now you can configure API keys and edit `initialize.py` for [Choosing Your LLMs](#choosing-your-llms).
-4. **Run Agent Zero:** Run Agent Zero by running the .exe file just created (Windows), or by running `./agent-zero` in your terminal window.
+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".
+2. Based on your operating system, download the right installer of miniconda. For macOS select the version with "pkg" at the end.
+
+<img src="res/setup/image-1.png" alt="miniconda download win" width="500"/>
+<img src="res/setup/image-5.png" alt="miniconda download macos" width="500"/>
+<br><br>
+
+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.
+
+<img src="res/setup/image.png" alt="miniconda install" width="200"/>
+<img src="res/setup/image-2.png" alt="miniconda install" width="200"/>
+<img src="res/setup/image-3.png" alt="miniconda install" width="200"/>
+<img src="res/setup/image-4.png" alt="miniconda install" width="200"/>
+<br><br>
+
+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.
+
+<img src="res/setup/image-6.png" alt="miniconda installed" height="100"/>
+<img src="res/setup/image-7.png" alt="miniconda installed" height="100"/>
+<br><br>
+
+
+## 2. Download Agent Zero
+- You can clone the Agent Zero repository (https://github.com/frdel/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/frdel/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.
+
+<img src="res/setup/image-14-u.png" alt="agent zero download" width="500"/>
+<br><br>
+
+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.
+
+<img src="res/setup/image-15.png" alt="agent zero cd" height="100"/>
+<img src="res/setup/image-16.png" alt="agent zero cd" height="100"/>
+<br><br>
+
+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.
+
+<img src="res/setup/image-17.png" alt="conda env" height="200"/>
+<img src="res/setup/image-18.png" alt="conda env" height="200"/>
+<br><br>
+
+> [!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.
+
+<img src="res/setup/image-19.png" alt="conda reqs" height="200"/>
+<br><br>
+
+## 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.
+
+<img src="res/setup/image-8.png" alt="docker download" width="200"/>
+<br><br>
+
+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.
+
+<img src="res/setup/image-9.png" alt="docker install" width="300"/>
+<img src="res/setup/image-10.png" alt="docker install" width="300"/>
+
+<img src="res/setup/image-12.png" alt="docker install" width="300"/>
+<br><br>
+
+
+4. Once installed, you should see Docker Desktop application on your Windows/Mac machine. 
+
+<img src="res/setup/image-11.png" alt="docker installed" height="100"/>
+<img src="res/setup/image-13.png" alt="docker installed" height="100"/>
+<br><br>
+
+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.
+
+![docker socket macOS](res/setup/macsocket.png)
+
+> [!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.
+
+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.
+
+## 5. Run the local Agent Zero instance
+Run the Agent Zero with Web UI:
+~~~
+python run_ui.py
+~~~
+
+<img src="res/setup/image-21.png" alt="run ui" height="110"/>
+<br><br>
+
+- 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.
+
+## 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"
+
+![rfc local settings](res/setup/9-rfc-devpage-on-local-sbs-1.png)
+
+5. Go in "Settings" page in the Web UI of your Docker instance and go in the "Development" section.
+
+![rfc docker settings](res/setup/9-rfc-devpage-on-docker-instance-1.png)
+
+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.
+
+<img src="res/setup/image-22-1.png" alt="run ui" width="400"/>
+<img src="res/setup/image-23-1.png" alt="run ui" width="400"/>
+<br><br>
 
-> [!WARNING]  
-> The 2 scripts will create executable files valid only for the machine where they 
-> are run. If you want to run Agent Zero on another machine, you will need to run 
-> the scripts on that machine as well to have executable files.
       
 ### 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.  If you encounter any issues during the installation process, please consult the Troubleshooting section of this documentation or refer to the Agent Zero community for assistance.
+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. 
+
+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/Z2tun2N3) community for assistance.
+

docs/res/web-ui.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2f689416c8938a6e649224e2a56b2d7d7235338e046969df71fc09a65391590c
+size 2371652

docs/troubleshooting.md

@@ -2,54 +2,42 @@
 This page addresses frequently asked questions (FAQ) and provides troubleshooting steps for common issues encountered while using Agent Zero.
 
 ## Frequently Asked Questions
-**1. How do I set up and activate a Python virtual environment?**
-Use the `venv` module or `conda` (recommended).
-* **`venv`:**
-    ```bash
-    python -m venv .venv  # Create the environment
-    source .venv/bin/activate  # Activate (Linux/macOS)
-    .venv\Scripts\activate  # Activate (Windows)
-    ```
-* **`conda`:**
-    ```bash
-    conda create -n agent-zero python=3.12  # Create
-    conda activate agent-zero  # Activate
-    ```
-**2. How do I resolve `ModuleNotFoundError` errors (e.g., for `ansio`, `pyflakes`, `Flask`)?**
-Ensure your virtual environment is activated *before* installing requirements:
-
-```bash
-pip install -r requirements.txt
-```
+**1. How do I ask Agent Zero to work directly on my files or dirs?**
+-   Place the files/dirs in the `work_dir` directory. Agent Zero will be able to perform tasks on them. The `work_dir` directory is located in the root directory of the Docker Container.
+
+**2. When I input something in the chat, nothing happens. What's wrong?**
+-   Check if you have set up API keys in the Settings page. If not, the application will not be able to communicate with the endpoints it needs to run LLMs and to perform tasks.
 
 **3. How do I integrate open-source models with Agent Zero?**
-Refer to the [Choosing your LLMs](installation.md#installing-and-using-ollama-local-models) section of the documentation for detailed instructions and examples for configuring different LLMs in `initialize.py`. Local models can be run using Ollama or LM Studio.
+Refer to the [Choosing your LLMs](installation.md#installing-and-using-ollama-local-models) section of the documentation for detailed instructions and examples for configuring different LLMs. Local models can be run using Ollama or LM Studio.
 
-> [!TIP]  
+> [!TIP]
 > Some LLM providers offer free usage of their APIs, for example Groq, Mistral or SambaNova.
 
-**4. How can I make Agent Zero retain memory between sessions?**
-Auto memory automatically saves and loads solutions and informations from previous sessions.
+**6. How can I make Agent Zero retain memory between sessions?**
+Refer to the [How to update Agent Zero](installation.md#how-to-update-agent-zero) section of the documentation for instructions on how to update Agent Zero while retaining memory and data.
 
-**5. Where can I find more documentation or tutorials?**
-*   Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/Z2tun2N3) community for support and discussions.
+**7. Where can I find more documentation or tutorials?**
+-   Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/Z2tun2N3) community for support and discussions.
 
-**6. How do I adjust API rate limits?**
+**8. How do I adjust API rate limits?**
 Modify the `rate_limit_seconds` and `rate_limit_requests` parameters in the `AgentConfig` class within `initialize.py`.
 
-**7. Can Agent Zero interact with external APIs or services (e.g., WhatsApp)?**
+**9. My code_execution_tool doesn't work, what's wrong?**
+-   Ensure you have Docker installed and running.  If using Docker Desktop on macOS, grant it access to your project files in Docker Desktop's settings.  Check the [Installation guide](installation.md#4-install-docker-docker-desktop-application) for more details.
+-   Verify that the Docker image is updated.
+
+**10. Can Agent Zero interact with external APIs or services (e.g., WhatsApp)?**
 Extending Agent Zero to interact with external APIs is possible by creating custom tools or solutions. Refer to the documentation on creating them. 
 
 ## Troubleshooting
 
 **Installation**
-* **Dependency Conflicts:** If encountering version conflicts during installation, try creating a fresh virtual environment and reinstalling the requirements.
-* **Docker Issues:** If Docker containers fail to start or Agent Zero can't connect to Docker, consult the Docker documentation and verify your Docker installation and configuration.  On macOS, ensure you've granted Docker access to your project files in Docker Desktop's settings as described in the [Installation guide](installation.md#2-install-docker-docker-desktop-application).
+- **Docker Issues:** If Docker containers fail to start or Agent Zero can't connect to Docker, consult the Docker documentation and verify your Docker installation and configuration.  On macOS, ensure you've granted Docker access to your project files in Docker Desktop's settings as described in the [Installation guide](installation.md#4-install-docker-docker-desktop-application). Verify that the Docker image is updated.
 
 **Usage**
-* **"Nothing happens" when sending a message:** This often indicates a tool execution issue, an API connection problem, or rate limiting. Check your API keys, internet connection, and ensure any required services (like Docker) are running.  Examine the logs for more details.
 
-* **Terminal commands not executing:** If using Docker for code execution, ensure the Docker container is running and properly configured.  Check SSH settings if applicable.
+- **Terminal commands not executing:** If using Docker for code execution, ensure the Docker container is running and properly configured.  Check SSH settings if applicable. Check if the Docker image is updated by removing it from Docker Desktop app, and subsequently prompting Agent Zero to `run an Hello World in Python`.
 
 * **Error Messages:** Pay close attention to the error messages displayed in the Web UI or terminal.  They often provide valuable clues for diagnosing the issue. Refer to the specific error message in online searches or community forums for potential solutions.
 

docs/usage.md

@@ -1,20 +1,106 @@
 # Usage Guide
-This guide explores more advanced usage scenarios for Agent Zero, building upon the basics covered in the [Quick Start](quickstart.md).
+This guide explores usage and configuration scenarios for Agent Zero. You can consider this as a reference post-installation guide.
 
 ![Utility Message with Solutions](res/memory-man.png)
 
-## Tool Usage
-Agent Zero's power comes from its ability to use [tools](architecture.md#tools). Here's how to leverage them effectively:
+## Basic Operations
+Agent Zero provides several basic operations through its interface:
 
-- **Understand Tools:** Agent Zero typically includes default tools like knowledge, webpage content, code execution, and communication.  Understand the capabilities of these tools and how to invoke them.
+### Restart Framework
+The Restart button allows you to quickly restart the Agent Zero framework without using the terminal:
 
-## Prompt Engineering
-Effective prompt engineering is crucial for getting the most out of Agent Zero. Here are some tips and techniques:
+![Restart Framework](res/ui-restarting.png)
 
-* **Be Clear and Specific:** Clearly state your desired outcome.  The more specific you are, the better Agent Zero can understand and fulfill your request.  Avoid vague or ambiguous language.
-* **Provide Context:** If necessary, provide background information or context to help the agent understand the task better. This might include relevant details, constraints, or desired format for the response.
-* **Break Down Complex Tasks:**  For complex tasks, break them down into smaller, more manageable sub-tasks.  This makes it easier for the agent to reason through the problem and generate a solution.
-* **Iterative Refinement:** Don't expect perfect results on the first try.  Experiment with different prompts, refine your instructions based on the agent's responses, and iterate until you achieve the desired outcome. To achieve a full-stack, web-app development task, for example, you might need to iterate for a few hours for 100% success.
+* Click the "Restart" button in the sidebar
+* A blue notification will appear indicating "Restarting..."
+* Once complete, a green success message "Restarted" will be shown
+* The framework will reinitialize while maintaining your current chat history and context
+
+> [!TIP]
+> Use the Restart function when you want to:
+> - Reset the framework if you encounter unexpected behavior
+> - Reinitialize the system when agents become unresponsive
+
+### Action Buttons
+Located beneath the chat input box, Agent Zero provides a set of action buttons for enhanced control and visibility:
+
+![Action Buttons](res/ui-actions.png)
+#### Chat Flow Control
+* **Pause/Resume Agent:** Toggle button to pause and resume chat flow
+  - Click to pause ongoing agent operations
+  - Changes to "Resume Agent" when paused
+  - Click again to resume chat flow and command execution
+
+#### Knowledge and File Management
+* **Import Knowledge:** Import external files into the agent's knowledge base
+  - Supports `.txt`, `.pdf`, `.csv`, `.html`, `.json`, and `.md` formats
+  - Files are stored in `\knowledge\custom\main`
+  - Success message confirms successful import
+  - See [knowledge](architecture.md#knowledge) for more details
+
+### File Browser: Manage files in the Agent Zero environment
+  - Upload new files and folders
+  - Download files (click filename) or folders (as zip archives)
+  - Delete files and folders
+  - Navigate directories using the "Up" button
+  - Support for file renaming and search coming soon
+  - See [File Browser](#file-browser) section for detailed features
+
+#### Debugging and Monitoring
+* **Context:** View the complete context window sent to the LLM
+  - Includes system prompts
+  - Shows current conversation context
+  - Displays active instructions and parameters
+
+![Context](res/ui-context.png)
+
+### History: 
+Access the chat history in JSON format
+  - View the conversation as processed by the LLM
+  - Useful for debugging and understanding agent behavior
+
+![History](res/ui-history.png)
+
+* **Nudge:** Restart the agent's last process
+  - Useful when agents become unresponsive
+  - Retries the last operation
+  - Helps recover from stuck states
+
+![Nudge](res/ui-nudge.png)
+
+> [!TIP]
+> Use the Context and History buttons to understand how the agent interprets your instructions and debug any unexpected behavior.
+
+### File Attachments
+Agent Zero supports direct file attachments in the chat interface for seamless file operations:
+
+#### Attaching Files
+* Click the attachment icon (📎) on the left side of the chat input box
+* Select one or multiple files to attach
+* Preview attached files before sending:
+  - File names are displayed with their types (HTML, PDF, JPG, etc.)
+  - Images show thumbnails when available
+  - Files are listed in the chat input area waiting to be sent
+
+![File Attachments](res/ui-attachments.png)
+
+#### Working with Attached Files
+* Files can be referenced directly in your messages
+* Agent Zero can:
+  - Process attached files
+  - Move files to specific directories
+  - Perform operations on multiple files simultaneously
+  - Confirm successful file operations with detailed responses
+
+![Working with Attachments](res/ui-attachments-2.png)
+
+> [!TIP]
+> When working with multiple files, you can attach them all at once and then give instructions about what to do with them. The agent will handle them as a batch while keeping you informed of the progress.
+
+## Tool Usage
+Agent Zero's power comes from its ability to use [tools](architecture.md#tools). Here's how to leverage them effectively:
+
+- **Understand Tools:** Agent Zero includes default tools like knowledge (powered by SearXNG), webpage content, code execution, and communication. Understand the capabilities of these tools and how to invoke them.
 
 ## Example of Tools Usage: Web Search and Code Execution
 Let's say you want Agent Zero to perform some financial analysis tasks. Here's a possible prompt:
@@ -28,12 +114,10 @@ Agent Zero might then:
 3. Use the `code_execution_tool` to execute a Python script that performs the graph creation and key points highlighting, using the extracted data and the news dates as inputs.
 4. Return the final chart that you'll find in `/work_dir`, responding to the user with the `response_tool`.
 
-This example demonstrates how to combine multiple tools to achieve an analysis task. By mastering prompt engineering and tool usage, you can unlock the full potential of Agent Zero to solve complex problems.
+> [!NOTE]
+> The first run of `code_execution_tool` may take a while as it downloads and builds the Agent Zero Docker image. Subsequent runs will be faster.
 
-## Memory Management
-* **Persistence:** Agent Zero's memory persists across sessions, allowing agents to learn from past interactions.
-* **Memory Retrieval:** Agents can access their [memory](architecture.md#memory-system) to retrieve relevant information and experiences.
-* **Knowledge Base:** You can augment the agent's knowledge by providing [external knowledge files](architecture.md#knowledge).
+This example demonstrates how to combine multiple tools to achieve an analysis task. By mastering prompt engineering and tool usage, you can unlock the full potential of Agent Zero to solve complex problems.
 
 ## Multi-Agent Cooperation
 One of Agent Zero's unique features is multi-agent cooperation.
@@ -45,51 +129,126 @@ One of Agent Zero's unique features is multi-agent cooperation.
 ![](res/physics.png)
 ![](res/physics-2.png)
 
-## Agent Behavior
-* **System Prompt:**  The core of Agent Zero's behavior is defined in the system prompt.  Experiment with different system prompts to customize the agent's personality, biases, and reasoning approach.
-* **Prompts Directory:** The `prompts` directory contains various prompt templates used by the framework. You can modify these templates to customize the agent's communication style, instructions, and responses. See [Prompt Customization](architecture.md#custom-prompts) for more information.
-* **Creating New Tools and Instruments:** Extend Agent Zero's capabilities with custom tools and instruments. This allows you to add new features, modify existing behavior, and integrate with other systems. See [Adding Tools](architecture.md#adding-tools) and [Adding Instruments](architecture.md#adding-instruments) for more information.
+## Prompt Engineering
+Effective prompt engineering is crucial for getting the most out of Agent Zero. Here are some tips and techniques:
+
+* **Be Clear and Specific:** Clearly state your desired outcome.  The more specific you are, the better Agent Zero can understand and fulfill your request.  Avoid vague or ambiguous language.
+* **Provide Context:** If necessary, provide background information or context to help the agent understand the task better. This might include relevant details, constraints, or desired format for the response.
+* **Break Down Complex Tasks:**  For complex tasks, break them down into smaller, more manageable sub-tasks.  This makes it easier for the agent to reason through the problem and generate a solution.
+* **Iterative Refinement:** Don't expect perfect results on the first try.  Experiment with different prompts, refine your instructions based on the agent's responses, and iterate until you achieve the desired outcome. To achieve a full-stack, web-app development task, for example, you might need to iterate for a few hours for 100% success.
+
+## Voice Interface
+Agent Zero provides both Text-to-Speech (TTS) and Speech-to-Text (STT) capabilities for natural voice interaction:
+
+### Text-to-Speech
+Enable voice responses from agents:
+* Toggle the "Speech" switch in the Preferences section of the sidebar
+* Agents will use your system's built-in voice synthesizer to speak their messages
+* Click the "Stop Speech" button above the input area to immediately stop any ongoing speech
+
+![TTS Stop Speech](res/ui-tts-stop-speech.png)
 
-## Using Agent Zero on your mobile device
-To access the Agent Zero Web UI from other devices on your network and run it on all hosts, such as your smartphones or tablets:
+- The interface allows users to stop speech at any time if a response is too lengthy or if they wish to intervene during the conversation.
 
-1.  In `run_ui.py`, add `host="0.0.0.0"` (or your private IP) to the `app.run()` command before the `port` argument (end of `run_ui.py`). The edited line of code should look like this:
-```python
-app.run(request_handler=NoRequestLoggingWSGIRequestHandler, host="0.0.0.0", port=port)
-```
-2. Access the Web UI from other devices using `http://$YOUR_PRIVATE_IP:50001`.
+The TTS uses a standard voice interface provided by modern browsers, which may sound robotic but is effective and does not require complex AI models. This ensures low latency and quick responses across various platforms, including mobile devices.
+
+
+> [!TIP]
+> The Text-to-Speech feature is great for:
+> - Multitasking while receiving agent responses
+> - Accessibility purposes
+> - Creating a more interactive experience
+
+### Speech-to-Text
+Send voice messages to agents using OpenAI's Whisper model (does not require OpenAI API key!):
+
+1. Click the microphone button in the input area to start recording
+2. The button color indicates the current status:
+   - Grey: Inactive
+   - Red: Listening
+   - Green: Recording
+   - Teal: Waiting
+   - Cyan (pulsing): Processing
+
+Users can adjust settings such as silence threshold and message duration before sending to optimize their interaction experience.
+
+Configure STT settings in the Settings page:
+* **Model Size:** Choose between Base (74M, English) or other models
+  - Note: Only Large and Turbo models support multiple languages
+* **Language Code:** Set your preferred language (e.g., 'en', 'fr', 'it', 'cz')
+* **Silence Detection:**
+  - Threshold: Adjust sensitivity (lower values are more sensitive)
+  - Duration: Set how long silence should last before ending recording
+  - Timeout: Set maximum waiting time before closing the microphone
+
+![Speech to Text Settings](res/ui-settings-5-speech-to-text.png)
+
+> [!IMPORTANT]
+> All STT and TTS functionalities operate locally within the Docker container, 
+> ensuring that no data is transmitted to external servers or OpenAI APIs. This 
+> enhances user privacy while maintaining functionality.
+
+### Mathematical Expressions
+Agent Zero supports KaTeX for beautiful mathematical typesetting:
+
+* **Inline Math:** Use single dollars `$...$` for inline expressions
+  - Example: Type `The area of a circle is $A = πr^2$`
+  - Renders as: The area of a circle is $A = πr^2$
+
+* **Display Math:** Use double dollars `$$...$$` for centered display equations
+  - Example: Type `$$F = G\frac{m_1m_2}{r^2}$$`
+  - Renders as a centered equation
+
+![KaTeX](res/ui-katex-1.png)
+
+* **Complex Mathematics:** Supports full KaTeX syntax for:
+  - Fractions, exponents, and roots
+  - Matrices and arrays
+  - Greek letters and mathematical symbols
+  - Integrals, summations, and limits
+  - Mathematical alignments and equations
+
+![KaTeX display](res/ui-katex-2.png)
+
+> [!TIP]
+> When asking the agent to solve mathematical problems, it will automatically respond using KaTeX formatting for clear and professional-looking mathematical expressions.
+
+### File Browser
+Agent Zero provides a powerful file browser interface for managing your workspace:
+
+#### Interface Overview
+- **Navigation Bar**: Shows current directory path with "Up" button for parent directory
+- **File List**: Displays files and directories with key information:
+  - Name (sortable)
+  - Size in bytes
+  - Last modified timestamp
+- **Action Icons**: Each file/directory has:
+  - Download button
+  - Delete button (with confirmation)
+
+![File Browser](res/ui-file-browser.png)
+
+#### Features
+- **Directory Navigation**: 
+  - Click directories to enter them
+  - Use "Up" button to move to parent directory
+  - Current path always visible for context
+
+> [!NOTE]
+> The files browser allows the user to go in the Agent Zero root folder if you click the `Up` button, but the working directory of Agents will always be `/work_dir`
+> 
+- **File Operations**:
+  - Create new files and directories
+  - Delete existing files and directories
+  - Download files to your local system
+  - Upload files from your local system
+- **File Information**:
+  - Visual indicators for file types (folders, code files, documents)
+  - Size information in human-readable format
+  - Last modification timestamps
+- **Bulk Operations**:
+  - Upload multiple files simultaneously
+  - Select and manage multiple files at once
 
 > [!TIP]
-> On local networks, the private address is usually 192.168.x.x or 10.0.x.x.
-> If you're using a VPN, you may need to use your public IP address instead of your 
-> private IP. You can find your public IP address by visiting a website like
-> [https://www.whatismyip.com/](https://www.whatismyip.com/).
->
-> If you're using a cloud server, you can use the server's public IP address instead 
-> of your private IP. You may need to configure your server's firewall to allow 
-> incoming traffic on port 50001.
-> If you're using a remote server, you may need to use a service like [ngrok]
-> (https://ngrok.com/) to create a secure tunnel to your server. This allows you to 
-> access the Web UI from other devices using a public URL.
-
-## Using code_execution_tool outside of the Docker Container
-> [!CAUTION]
-> We believe in safe and ethical AI development, and highly 
-> suggest you to use the Docker container designed for running Agent Zero.
-> However, we understand that some users may want to use the code_execution_tool outside of the Docker container.
->
-> This is a dangerous and untested feature, and we are not responsible for any damage 
-> or illegal activities or legal liabilities caused by the use of this feature. 
-> As you are responsible for your own actions, use this feature only if 100% sure of what you're doing.
-
-- If you accept the risks, follow these steps:
-
-    ![Code Execution Jailbreak](res/code_exec_jailbreak.png)
-
-1. After the installation and configuration of your Agent Zero instance, go in `initialize.py` and set the `code_exec_docker_enabled` to `False` (line 47). This will disable the code_execution_tool for your Agent Zero instance to communicate with the Docker container. The tool will search for an SSH connection at this point.
-
-2. Comment out lines 56, 57, 58 and 59 in `initialize.py` that sets the `code_execution_tool` SSH connection parameters. Point them to your machine accordingly. This will enable the code_execution_tool for your Agent Zero instance.
-
-> [!IMPORTANT] 
-> The `code_exec_ssh_pass` parameter (root user password) has to be provided to 
-> `initialize.py` for the code_execution_tool to be able to connect to the machine.
+> The File Browser integrates seamlessly with Agent Zero's capabilities. You can reference files directly in your conversations, and the agent can help you manage, modify, and organize your files.

knowledge/default/main/about/github_readme.md

@@ -3,15 +3,15 @@
 [![Join our Skool Community](https://img.shields.io/badge/Skool-Join%20our%20Community-4A90E2?style=for-the-badge&logo=skool&logoColor=white)](https://www.skool.com/agent-zero) [![Join our Discord](https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/B8KZKNsPpj) [![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/@AgentZeroFW) [![Connect on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/jan-tomasek/) [![Follow on X.com](https://img.shields.io/badge/X.com-Follow-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/JanTomasekDev)
 
 
-[![Intro Video](/docs/res/intro_vid.jpg)](https://www.youtube.com/watch?v=C9n8zFpaV3I)
+[![Intro Video](/docs/res/new_vid.jpg)](https://www.youtube.com/watch?v=U_Gl0NPalKA)
 
 **Personal and organic AI framework**
 - 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.
 
-## Now with UI:
-![UI prototype](/docs/res/ui_screen1.png)
+## Now fully Dockerized, fully UI, with TTS and STT:
+![Web UI](/docs/res/win_webui2.gif)
 
 ## Key concepts
 1. **General-purpose assistant**
@@ -23,6 +23,10 @@
 - 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, webpage content, code execution, and communication. 
+* **Creating Custom Tools:**  Extend Agent Zero's functionality by creating your own custom tools.
+* **Instruments:**  Instruments are a new type of tool that allow you to create custom functions and procedures that can be called by Agent Zero.
+
 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.
@@ -51,9 +55,11 @@
 - No coding is required, only prompting and communication skills.
 - With a solid system prompt, the framework is reliable even with small models, including precise tool usage.
 
+![Agent 1 System Load](/docs/res/ui_screen.png)
+
 ## Keep in mind
 1. **Agent Zero can be dangerous!**
-With proper instruction, Agent Zero is capable of many things, even potentially dangerous to your computer, data, or accounts. Always run Agent Zero in an isolated environment (like the built in docker container) and be careful what you wish for.
+With proper instruction, Agent Zero is capable of many things, even potentially dangerous to your computer, data, or accounts. Always run Agent Zero in an isolated environment (like the one provided with Docker) and be careful what you wish for.
 
 2. **Agent Zero is not pre-programmed; it is prompt-based.**
 The whole framework contains only a minimal amount of code and does not guide the agent in any way.
@@ -64,26 +70,63 @@ If your agent fails to communicate properly, use tools, reason, use memory, find
 Agent Zero is made to be used in an isolated virtual environment (for safety) with some tools preinstalled and configured.
 If you cannot provide all the necessary conditions or API keys, just change the system prompt and tell your agent what operating system and tools are at its disposal. Nothing is hard-coded; if you do not tell your agent about a certain tool, it will not know about it and will not try to use it.
 
-
 [![David Ondrej video](/docs/res/david_vid.jpg)](https://www.youtube.com/watch?v=_Pionjv4hGc)
 
 ## Known problems
 1. The system prompt sucks. You can do better. If you do, help me please :)
-2. The communication between agent and terminal in docker container via SSH can sometimes break and stop producing outputs. Sometimes it is because the agent runs something like "server.serve_forever()" which causes the terminal to hang, sometimes a random error can occur. Restarting the agent and/or the docker container helps.
-3. The agent can break his operating system. Sometimes the agent can deactivate virtual environment, uninstall packages, change config etc. Again, removing the docker container and cleaning up the **work_dir/** is enough to fix that.
+2. The communication between agents and terminal in Docker Container via SSH can sometimes break and stop producing outputs. Sometimes it is because the agent runs something like "server.serve_forever()" which causes the terminal to hang, sometimes a random error can occur. Restarting the agent and/or the Docker container helps.
+3. The agent can break his operating system. Sometimes the agent can deactivate virtual environment, uninstall packages, change config etc. Again, removing the Docker container and cleaning up the **work_dir/** is enough to fix that.
 
 ## Ideal environment
-- **Docker container**: The perfect environment to run Agent Zero is the built-in docker container. The agent can download the image **frdel/agent-zero-exe** on its own and start the container, you only need to have docker running (like the Docker Desktop application).
+- **Docker container**: The perfect environment to run Agent Zero is the built-in Docker container. The agent can download the image **frdel/agent-zero-exe** on its own and start the container, you only need to have Docker running (like the Docker Desktop application).
 - **Python**: Python has to be installed on the system to run the framework.
 - **Internet access**: The agent will need internet access to use its online knowledge tool and execute commands and scripts requiring a connection. If you do not need your agent to be online, you can alter its prompts in the **prompts/** folder and make it fully local.
 
 ![Time example](/docs/res/time_example.jpg)
 
 ## Setup
-
-A detailed setup guide with a video can be found here: [/docs/installation](https://github.com/frdel/agent-zero/tree/main/docs/installation). Scroll down to see the readme file.
-
-> ⚠️ **Changes to launch files since v0.6:**  
-> main.py file has been replaced with run_ui.py (webui) and run_cli.py (terminal) launch files.
-> configuration has been moved to initialize.py for both webui and terminal launch files.
-
+A detailed setup guide for Windows, macOS and Linux with a video can be found in the new Agent Zero Documentation at [this page](docs/installation.md#windows-macos-and-linux-setup-guide). 
+
+You can download the executable for your system from the [releases page](https://github.com/frdel/agent-zero/releases).
+
+## Consult the Documentation
+The documentation dives deep into the framework and its features. It is a good place to start if you are new to Agent Zero. Click [here](docs/README.md) to see the Documentation.
+
+## Coming up
+- **User interaction refinements**
+- **Browser use and RAG tools**
+
+### Changelog [since version 0.7]
+
+#### v0.7.1
+- **Preinstalled binaries and bundler scripts**
+- **Persistent Chats** - Serialized to /tmp/chats and automatically loaded in run_ui.py on startup
+- **Documentation stack merged into the repository**
+- **Bug Fixes**
+
+> [!NOTE]  
+> **Changes to frdel/agent-zero Docker image since v0.8:**  
+> - In version 0.8, the Docker image has changed to frdel/agent-zero-run using the new Dockerfile.
+
+#### v0.8
+- **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 knowledge_tool**
+- **File browser functionality**
+- **KaTeX math visualization support**
+- **In-chat file attachments**
+
+#### v0.7
+- **Automatic memory**
+- **UI improvements**
+- **Instruments**
+- **Extensions framework**
+- **Reflection prompts**
+- **Bugfixes**
+
+> [!NOTE]  
+> **Changes to launch files since v0.7:**  
+> - the Docker image has been changed to frdel/agent-zero-run from the legacy installation process.

knowledge/default/main/about/installation.md

@@ -1,95 +1,371 @@
-# How to install Agent Zero on Windows and MacOS
-- Agent Zero is not an app. It's a framework. It's made to be customized, edited, enhanced. Therefore you need to install the necessary components to run it.
-- I will provide step by step instructions along with a video for this tutorial on how to make Agent Zero work on Windows and MacOS.
+# Users installation guide for Windows, macOS and Linux
 
-[![Video](thumb_play.png)](https://youtu.be/8H7mFsvxKYQ)
+[![Setup Guide](res/setup/thumb_setup.png)](https://www.youtube.com/watch?v=wWAqJpl3uQE)
 
-## Reminders:
-1. You don't need to install Python, Conda will take care of that for you.
-2. You don't need API keys, Agent Zero can run with local models, but for this tutorial I will leave it to the default OpenAI API. Local models will be covered in another tutorial.
-3. You don't need Visual Studio Code or any other code editor, but it's easier to navigate and edit files if you have one.
-4. Docker is not mandatory, but running Agent Zero without docker is actually more complicated and can be very dangerous, so I will be showing the easier and recommended way to do it - with Docker Desktop application.
-5. Git/Github is not mandatory, you can download the framework files in browser. I will not be showing how to use Git in this tutorial.
+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).
 
+### Maybe you're looking for this? 👉[How to update Agent Zero](#how-to-update-agent-zero)
 
-## 1. Install Conda (miniconda)
-- Conda is a python environment manager, it will help you keep your projects and installations separated. Full Conda has many more features, but you only need "miniconda".
+## Windows, macOS and Linux Setup Guide
 
-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".
-2. Based on your operating system, download the right installer of miniconda. For MacOS select the version with "pkg" at the end.
+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
 
-<img src="image-1.png" alt="miniconda download win" width="500"/>
-<img src="image-5.png" alt="miniconda download macos" width="500"/>
-<br><br>
+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".
 
-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.
+1.2. Download the version for your operating system. For Windows users, the Intel/AMD version is the main download button.
 
-<img src="image.png" alt="miniconda install" width="200"/>
-<img src="image-2.png" alt="miniconda install" width="200"/>
-<img src="image-3.png" alt="miniconda install" width="200"/>
-<img src="image-4.png" alt="miniconda install" width="200"/>
+<img src="res/setup/image-8.png" alt="docker download" width="200"/>
 <br><br>
 
-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.
+> [!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.
+
+<img src="res/setup/image-9.png" alt="docker install" width="300"/>
+<img src="res/setup/image-10.png" alt="docker install" width="300"/>
+
+<img src="res/setup/image-12.png" alt="docker install" width="300"/>
+<br><br>
 
-<img src="image-6.png" alt="miniconda installed" height="100"/>
-<img src="image-7.png" alt="miniconda installed" height="100"/>
+1.4. Once installed, launch Docker Desktop: 
+
+<img src="res/setup/image-11.png" alt="docker installed" height="100"/>
+<img src="res/setup/image-13.png" alt="docker installed" height="100"/>
 <br><br>
 
-## 2. 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.
-- Running Agent Zero without docker is possible, but more complicated and dangerous, I will not be covering that in this tutorial.
-- Docker has a desktop application with GUI for all major operating system, so I will be using that.
+1.5. Create a Docker Hub account when prompted and sign in. This is required to pull the Agent Zero container image.
 
-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.
+> [!IMPORTANT]  
+> **macOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings → 
+> Advanced, enable "Allow the default Docker socket to be used (requires password)."
 
-<img src="image-8.png" alt="docker download" width="200"/>
-<br><br>
+![docker socket macOS](res/setup/macsocket.png)
+
+2. **Run Agent Zero:**
+
+2.1. Pull the Agent Zero Docker image:
+- Search for `frdel/agent-zero-run` in Docker Desktop
+- Click the `Pull` button
+- The image will be downloaded to your machine in a few minutes
+
+![docker pull](res/setup/1-docker-image-search.png)
+
+> [!TIP]
+> Alternatively, run the following command in your terminal:
+>
+> ```bash
+> docker pull frdel/agent-zero-run
+> ```
+
+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
+
+> [!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:
+- In Docker Desktop, go back to the "Images" tab
+- Click the `Run` button next to the `frdel/agent-zero-run` image
+- Open the "Optional settings" menu
+- Set the port to `0` in the second "Host port" field (for automatic port assignment)
+- Under "Volumes", configure:
+  - Host path: Your chosen directory (e.g., `C:\agent-zero-data`)
+  - Container path: `/a0`
 
-3. Run the installer and go through the installattion 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.
+![docker port mapping](res/setup/3-docker-port-mapping.png)
+
+- Click the `Run` button in the "Images" tab.
+- The container will start and show in the "Containers" tab
+
+![docker containers](res/setup/4-docker-container-started.png)
+
+> [!TIP]
+> Alternatively, run the following command in your terminal:
+> ```bash
+> docker run -p $PORT:80 -v /path/to/your/data:/a0 frdel/agent-zero-run
+> ```
+> - 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 `<PORT>:80`) or click the port right under the container ID as shown in the image below
+
+![docker logs](res/setup/5-docker-click-to-open.png)
+
+- Open `http://localhost:<PORT>` in your browser
+- The Web UI will open. Agent Zero is ready for configuration!
+
+![docker ui](res/setup/6-docker-a0-running.png)
+
+> [!TIP]
+> You can also access the Web UI by clicking the ports right under the container ID in Docker Desktop.
+
+> [!NOTE]
+> 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.
+
+3. Configure Agent Zero
+- Refer to the following sections for a full guide on how to configure Agent Zero.
+
+## Settings Configuration
+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.
+
+### Agent Configuration
+- **Prompts Subdirectory:** Choose the subdirectory within `/prompts` for agent behavior customization. The 'default' directory contains the standard prompts.
+- **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances.
+- **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding.
+
+![settings](res/setup/settings/1-agentConfig.png)
+
+### Chat Model Settings
+- **Provider:** Select the chat model provider (e.g., Ollama)
+- **Model Name:** Choose the specific model (e.g., llama3.2)
+- **Temperature:** Adjust response randomness (0 for deterministic, higher values for more creative responses)
+- **Context Length:** Set the maximum token limit for context window
+- **Context Window Space:** Configure how much of the context window is dedicated to chat history
+
+![chat model settings](res/setup/settings/2-chat-model.png)
+
+### Utility Model Configuration
+- **Provider & Model:** Select a smaller, faster model for utility tasks like memory organization and summarization
+- **Temperature:** Adjust the determinism of utility responses
+
+### Embedding Model Settings
+- **Provider:** Choose the embedding model provider (e.g., OpenAI)
+- **Model Name:** Select the specific embedding model (e.g., text-embedding-3-small)
+
+### Speech to Text Options
+- **Model Size:** Choose the speech recognition model size
+- **Language Code:** Set the primary language for voice recognition
+- **Silence Settings:** Configure silence threshold, duration, and timeout parameters for voice input
+
+### API Keys
+- Configure API keys for various service providers
+
+### Authentication
+- **UI Login:** Set username for web interface access
+- **UI Password:** Configure password for web interface security
+- **Root Password:** Manage Docker container root password for SSH access
+
+![settings](res/setup/settings/3-auth.png)
+
+### Development Settings
+- **RFC Parameters (local instances only):** configure URLs and ports for remote function calls between instances
+- **RFC Password:** Configure password for remote function calls
+Learn more about Remote Function Calls and their purpose [here](#7-configure-agent-zero-rfc).
+
+> [!IMPORTANT]
+> Always keep your API keys and passwords secure.
+
+# Choosing Your LLMs
+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:
+
+| LLM Role | Description |
+| --- | --- |
+| `chat_llm` | This is the primary LLM used for conversations and generating responses. |
+| `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. |
+| `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. |
+
+**How to Change:**
+1. Open Settings page in the Web UI.
+2. Change the LLM for each role (Chat model, Utility model, Embedding model).
+3. Click "Save" to apply the changes.
+
+## Important Considerations
+
+> [!CAUTION]
+> Changing the `embedding_llm` will re-index all the memory and knowledge, and 
+> requires clearing the `memory` folder to avoid errors, as the embeddings can't be 
+> mixed in the vector database. Note that this will DELETE ALL of Agent Zero's memory.
+
+- 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.
+
+## Using Agent Zero on your mobile device
+Agent Zero's Web UI is accessible from any device on your network through the Docker container:
+
+1. The Docker container automatically exposes the Web UI on all network interfaces
+2. Find the mapped port in Docker Desktop:
+   - Look under the container name (usually in the format `<PORT>:80`)
+   - For example, if you see `32771:80`, your port is `32771`
+3. Access the Web UI from any device using:
+   - Local access: `http://localhost:<PORT>`
+   - Network access: `http://<YOUR_COMPUTER_IP>:<PORT>`
+
+> [!TIP]
+> - Your computer's IP address is usually in the format `192.168.x.x` or `10.0.x.x`
+> - You can find your external IP address by running `ipconfig` (Windows) or `ifconfig` (Linux/Mac)
+> - The port is automatically assigned by Docker unless you specify one
+
+> [!NOTE]
+> If you're running Agent Zero directly on your system (legacy approach) instead of 
+> 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"`.
+
+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).
+
+### How to update Agent Zero
+
+1. **If you come from the previous version of Agent Zero (pre-0.7.1):**
+- Your data is safely stored across various directories and files inside the Agent Zero folder.
+- To update to the new Docker runtime version, you need to save the following files and directories:
+  - `/memory` - Agent's memory
+  - `/knowledge` - Custom knowledge base
+  - `/instruments` - Custom instruments and functions
+  - `/prompts` - Custom prompts files (if any has been created)
+  - `/work_dir` - Working directory
+  - `.env` - Your API keys
+  - `/tmp/settings.json` - Your Agent Zero settings
+- 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.
+- Reach for the folder where you saved your data and copy it to the new Agent Zero folder set during the installation process.
+- Agent Zero will automatically detect your saved data and use it across memory, knowledge, instruments, prompts and settings.
+
+> [!IMPORTANT]
+> Make sure to use the same embedding model you were using before, otherwise 
+> you will have to re-index all of Agent Zero's memory, therefore deleting all 
+> your custom knowledge and memory.
+
+> [!NOTE]
+> If you have issues loading your settings, you can try to delete the `/tmp/settings.json` 
+> file and let Agent Zero generate a new one.
+
+2. **Update Process (Docker Desktop)**
+- Go to Docker Desktop and stop the container from the "Containers" tab
+- Right-click and select "Remove" to remove the container
+- Go to "Images" tab and remove the `frdel/agent-zero-run` image
+
+![docker delete image](res/setup/docker-delete-image-1.png)
+
+- Search and pull the new image
+- Run the new container with the same volume settings as the old one
+
+> [!IMPORTANT]
+> Make sure to use the same volume mount path when running the new
+> container to preserve your data. The exact path depends on where you stored
+> your Agent Zero data directory (the chosen directory on your machine).
+
+> [!TIP]
+> Alternatively, run the following commands in your terminal:
+>
+> ```bash
+> # Stop the current container
+> docker stop agent-zero
+>
+> # Remove the container (data is safe in the folder)
+> docker rm agent-zero
+>
+> # Remove the old image
+> docker rmi frdel/agent-zero-run
+>
+> # Pull the latest image
+> docker pull frdel/agent-zero-run
+>
+> # Run new container with the same volume mount
+> docker run -p $PORT:80 -v /path/to/your/data:/a0 frdel/agent-zero-run
+> ```
+
+3. **Full Binaries**
+- Using Git/GitHub: Pull the latest version of the Agent Zero repository with. 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.
+
+> [!WARNING]  
+> - If you update manually, beware: save your .env file with the API keys, and look for new dependencies in requirements.txt. 
+> - 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:
+> ```bash
+> pip install -r requirements.txt
+
+# In-Depth Guide for Full Binaries Installation
+- 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.
+- 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.
+
+[![Video](res/setup/thumb_play.png)](https://youtu.be/8H7mFsvxKYQ)
+
+## Reminders:
+1. There's no need to install Python, Conda will manage that for you.
+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).
+3. Visual Studio Code or any other code editor is not mandatory, but it makes it easier to navigate and edit files.
+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.
+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.
+6. Running Agent Zero without Docker makes the process more complicated and it's thought for developers and contributors.
+
+> [!IMPORTANT]  
+> 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.
+>
+> For Debian/Ubuntu, just follow the macOS instructions, as they are the same.
+
+## 1. Install Conda (miniconda)
+- Conda is a Python environment manager, it will help you keep your projects and installations separated. 
+- 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.
 
-<img src="image-9.png" alt="docker install" width="300"/>
-<img src="image-10.png" alt="docker install" width="300"/>
+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".
+2. Based on your operating system, download the right installer of miniconda. For macOS select the version with "pkg" at the end.
 
-<img src="image-12.png" alt="docker install" width="300"/>
+<img src="res/setup/image-1.png" alt="miniconda download win" width="500"/>
+<img src="res/setup/image-5.png" alt="miniconda download macos" width="500"/>
 <br><br>
 
+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. Once installed, you should see Docker Desktop application on your Windows/Mac machine. 
+<img src="res/setup/image.png" alt="miniconda install" width="200"/>
+<img src="res/setup/image-2.png" alt="miniconda install" width="200"/>
+<img src="res/setup/image-3.png" alt="miniconda install" width="200"/>
+<img src="res/setup/image-4.png" alt="miniconda install" width="200"/>
+<br><br>
 
-<img src="image-11.png" alt="docker installed" height="100"/>
-<img src="image-13.png" alt="docker installed" height="100"/>
+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.
+
+<img src="res/setup/image-6.png" alt="miniconda installed" height="100"/>
+<img src="res/setup/image-7.png" alt="miniconda installed" height="100"/>
 <br><br>
 
-5. Create account in the application.
-No need to create images or containers, the framework will do that for you. However, this requires you 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.
 
-## 3. Download Agent Zero
-- You can clone the Agent Zero repository (https://github.com/frdel/agent-zero) from GitHub if you know how to use git. In this tutorial I will just show how to download the files.
+## 2. Download Agent Zero
+- You can clone the Agent Zero repository (https://github.com/frdel/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/frdel/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.
 
-<img src="image-14.png" alt="agent zero download" width="500"/>
+<img src="res/setup/image-14-u.png" alt="agent zero download" width="500"/>
 <br><br>
 
-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. 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.
 
-
-## 4. Set up Conda environment
+## 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.
+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.
 
-<img src="image-15.png" alt="agent zero cd" height="100"/>
-<img src="image-16.png" alt="agent zero cd" height="100"/>
+<img src="res/setup/image-15.png" alt="agent zero cd" height="100"/>
+<img src="res/setup/image-16.png" alt="agent zero cd" height="100"/>
 <br><br>
 
 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.
@@ -103,11 +379,13 @@ 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.
 
-<img src="image-17.png" alt="conda env" height="200"/>
-<img src="image-18.png" alt="conda env" height="200"/>
+<img src="res/setup/image-17.png" alt="conda env" height="200"/>
+<img src="res/setup/image-18.png" alt="conda env" height="200"/>
 <br><br>
 
-> ⚠️ If you open a new terminal window, you will need to activate the environment with "conda activate a0" again for that window.
+> [!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:
 ~~~
@@ -115,40 +393,148 @@ 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.
 
-<img src="image-19.png" alt="conda reqs" height="200"/>
+<img src="res/setup/image-19.png" alt="conda reqs" height="200"/>
 <br><br>
 
-## 5. Configure Agent Zero
-- Now we can configure Agent Zero - select models, settings, API Keys etc.
-- I will leave the default configuration using OpenAI API and I will just provide my OpenAI API key in the **.env** file.
+## 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. Find the **"example.env"** file in your Agent Zero folder and edit the contents. I will put my OpenAI API key after **"API_KEY_OPENAI="**. If you have API keys for other service providers, add them as needed.
-2. Rename the **"example.env"** file to **".env"**. This is important, only this exact "**.env**" file name is valid.
+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.
 
-<img src="image-20.png" alt="conda reqs" height="200"/>
+<img src="res/setup/image-8.png" alt="docker download" width="200"/>
 <br><br>
 
-3. (Optional) Change models or setting in **"initialize.py"** file if needed.
+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.
 
-## 6. Run Agent Zero
-- Setup done. It's time to test Agent Zero. Let's double check:
+<img src="res/setup/image-9.png" alt="docker install" width="300"/>
+<img src="res/setup/image-10.png" alt="docker install" width="300"/>
 
-1. Make sure you have the **"a0"** Conda environment still active in your current terminal window. You can see that on the left of each terminal line like **(a0)** or **(base)**. If not, activate again with **"conda activate a0"** command again.
-2. Make sure your terminal is looking into the Agent Zero folder. If not, navigate to it with **"cd"** command again with your path.
-3. Run the **Docker Desktop application** you installed and just leave it running in the background. No need to create images or containers, the framework will do that for you. However, this requires you to be signed in to the Docker Hub, so sign in in the Docker Desktop application, if you haven't already.
-4. Run the Agent Zero with Web UI:
+<img src="res/setup/image-12.png" alt="docker install" width="300"/>
+<br><br>
+
+
+4. Once installed, you should see Docker Desktop application on your Windows/Mac machine. 
+
+<img src="res/setup/image-11.png" alt="docker installed" height="100"/>
+<img src="res/setup/image-13.png" alt="docker installed" height="100"/>
+<br><br>
+
+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.
+
+![docker socket macOS](res/setup/macsocket.png)
+
+> [!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.
+
+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.
+
+## 5. Run the local Agent Zero instance
+Run the Agent Zero with Web UI:
 ~~~
 python run_ui.py
 ~~~
 
-<img src="image-21.png" alt="run ui" height="200"/>
+<img src="res/setup/image-21.png" alt="run ui" height="110"/>
 <br><br>
 
-5. Open the URL shown in terminal in your web browser. You should see the Agent Zero interface. The first time it needs to execute code, Docker image will be downloaded and deployed, this might take some time. Be patient when seeing "Initializing docker container agent-zero-exe for safe code execution...".
+- Open the URL shown in terminal in your web browser. You should see the Agent Zero interface.
 
-<img src="image-22.png" alt="run ui" width="400"/>
-<img src="image-23.png" alt="run ui" width="400"/>
+## 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.
+
+## 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"
+
+![rfc local settings](res/setup/9-rfc-devpage-on-local-sbs-1.png)
+
+5. Go in "Settings" page in the Web UI of your Docker instance and go in the "Development" section.
+
+![rfc docker settings](res/setup/9-rfc-devpage-on-docker-instance-1.png)
+
+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.
+
+<img src="res/setup/image-22-1.png" alt="run ui" width="400"/>
+<img src="res/setup/image-23-1.png" alt="run ui" width="400"/>
 <br><br>
 
+      
+### 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. 
+
+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/Z2tun2N3) community for assistance.
+
+## Installing and Using Ollama (Local Models)
+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:
+
+#### First step: installation
+**On Windows:**
+
+Download Ollama from the official website and install it on your machine.
+
+<button>[Download Ollama Setup](https://ollama.com/download/OllamaSetup.exe)</button>
+
+**On macOS:**
+```
+brew install ollama
+```
+Otherwise choose macOS installer from the [official website](https://ollama.com/).
+
+**On Linux:**
+```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).
+
+#### Second step: pulling the model
+**On Windows, macOS, and Linux:**
+```
+ollama pull <model-name>
+```
+
+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`.
 
+#### Managing your downloaded models
+Once you've downloaded some models, you might want to check which ones you have available or remove any you no longer need.
 
+- **Listing downloaded models:** 
+  To see a list of all the models you've downloaded, use the command:
+  ```
+  ollama list
+  ```
+- **Removing a model:**
+  If you need to remove a downloaded model, you can use the `ollama rm` command followed by the model name:
+  ```
+  ollama rm <model-name>
+  ```