docs stack update part i
Alessandro committed
Feb 10, 2026 at 13:25 UTC
8adf16540497806baeff067ac5947fcfef57eb94
25 files changed
+1210
-372
README.md
+55
-26
@@ -12,13 +12,13 @@
12
## Documentation:
13
14
[Introduction](#a-personal-organic-agentic-framework-that-grows-and-learns-with-you) •
15
-[Installation](./docs/installation.md) •
16
-[Development](./docs/development.md) •
17
-[WebSocket Infrastructure](./docs/websocket-infrastructure.md) •
18
-[Connectivity](./docs/connectivity.md) •
19
-[How to update](./docs/installation.md#how-to-update-agent-zero) •
15
+[Installation](./docs/getting-started/installation.md) •
16
+[Development](./docs/development/setup.md) •
17
+[WebSocket Infrastructure](./docs/advanced/websockets.md) •
18
+[Connectivity](./docs/advanced/connectivity.md) •
19
+[How to update](./docs/getting-started/installation.md#how-to-update-agent-zero) •
20
[Documentation](./docs/README.md) •
21
-[Usage](./docs/usage.md)
21
+[Usage](./docs/guides/usage.md)
22
23
Or see DeepWiki generated documentation:
24
@@ -30,7 +30,7 @@ Or see DeepWiki generated documentation:
30
<div align="center">
31
32
> ### 🚨 **PROJECTS!** 🚨
33
-Agent Zero now supports **Projects** – isolated workspaces with their own prompts, files, memory, and secrets, so you can create dedicated setups for each use case without mixing contexts.
33
+> Agent Zero now supports **Projects** – isolated workspaces with their own prompts, files, memory, and secrets, so you can create dedicated setups for each use case without mixing contexts.
34
</div>
35
36
@@ -38,7 +38,6 @@ Agent Zero now supports **Projects** – isolated workspaces with their own prom
38
[](https://youtu.be/lazLNcEYsiQ)
39
40
41
-
41
## A personal, organic agentic framework that grows and learns with you
42
43
@@ -105,14 +104,13 @@ Agent Zero now supports **Projects** – isolated workspaces with their own prom
104
- **Research** - `"Gather and summarize five recent AI papers about CoT prompting"`
105
106
108
-
107
# ⚙️ Installation
108
109
Click to open a video to learn how to install Agent Zero:
110
111
[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
112
115
-A detailed setup guide for Windows, macOS, and Linux with a video can be found in the Agent Zero Documentation at [this page](./docs/installation.md).
113
+A detailed setup guide for Windows, macOS, and Linux with a video can be found in the Agent Zero Documentation at [this page](./docs/getting-started/installation.md).
114
115
### ⚡ Quick Start
116
@@ -155,19 +153,57 @@ docker run -p 50001:80 agent0ai/agent-zero
153
154
| Page | Description |
155
|-------|-------------|
158
-| [Installation](./docs/installation.md) | Installation, setup and configuration |
159
-| [Usage](./docs/usage.md) | Basic and advanced usage |
160
-| [Development](./docs/development.md) | Development and customization |
161
-| [WebSocket Infrastructure](./docs/websocket-infrastructure.md) | Real-time WebSocket handlers, client APIs, filtering semantics, envelopes |
162
-| [Extensibility](./docs/extensibility.md) | Extending Agent Zero |
163
-| [Connectivity](./docs/connectivity.md) | External API endpoints, MCP server connections, A2A protocol |
164
-| [Architecture](./docs/architecture.md) | System design and components |
165
-| [Contributing](./docs/contribution.md) | How to contribute |
166
-| [Troubleshooting](./docs/troubleshooting.md) | Common issues and their solutions |
156
+| [Installation](./docs/getting-started/installation.md) | Installation, setup and configuration |
157
+| [Usage](./docs/guides/usage.md) | Basic and advanced usage |
158
+| [Development](./docs/development/setup.md) | Development and customization |
159
+| [WebSocket Infrastructure](./docs/advanced/websockets.md) | Real-time WebSocket handlers, client APIs, filtering semantics, envelopes |
160
+| [Extensibility](./docs/development/extensibility.md) | Extending Agent Zero |
161
+| [Connectivity](./docs/advanced/connectivity.md) | External API endpoints, MCP server connections, A2A protocol |
162
+| [Architecture](./docs/advanced/architecture.md) | System design and components |
163
+| [Contributing](./docs/development/contribution.md) | How to contribute |
164
+| [Troubleshooting](./docs/guides/troubleshooting.md) | Common issues and their solutions |
165
166
167
## 🎯 Changelog
168
169
+### v0.9.8 - Skills, UI Redesign & Git projects
170
+[Release video](https://youtu.be/NV7s78yn6DY)
171
+
172
+- Skills
173
+ - Skills System replacing the legacy Instruments with a new `SKILL.md` standard for structured, portable agent capabilities.
174
+ - Built-in skills, and UI support for importing and listing skills
175
+- Real-time WebSocket infrastructure replacing the polling-based approach for UI state synchronization
176
+- UI Redesign
177
+ - Process groups to visually group agent actions with expand/collapse support
178
+ - Timestamps, steps count and execution time with tool-specific badges
179
+ - Step detail modals with key-value and raw JSON display
180
+ - Collapsible responses with show more/less and copy buttons on code blocks and tables
181
+ - Message queue system allowing users to queue messages while the agent is still processing
182
+ - In-browser file editor for viewing and editing files without leaving the UI
183
+ - Welcome screen redesign with info and warning banners for connection security, missing API keys, and system resources
184
+ - Scheduler redesign with standalone modal, separate task list, detail and editor components, and project support
185
+ - Smooth response rendering and scroll stabilization across chat, terminals, and image viewer
186
+ - Chat width setting and reworked preferences panel
187
+ - Image viewer improvements with scroll support and expanded viewer
188
+ - Redesigned sidebar with reusable dropdown component and streamlined buttons
189
+ - Inline button confirmations for critical actions
190
+ - Improved login design and new logout button
191
+ - File browser enhanced with rename and file actions dropdown
192
+- Git projects
193
+ - Git-based projects with clone authentication for public and private repositories
194
+- Four new LLM providers: CometAPI, Z.AI, Moonshot AI, and AWS Bedrock
195
+- Microsoft Dev Tunnels integration for secure remote access
196
+- User data migration to `/usr` directory for cleaner separation of user and system files
197
+- Subagents system with configurable agent profiles for different roles
198
+- Memory operations offloaded to deferred tasks for better performance
199
+- Environment variables can now configure settings via `A0_SET_*` prefix in `.env`
200
+- Automatic migration with overwrite support for `.env`, scheduler, knowledge, and instruments directories
201
+- Projects support extended to MCP, A2A, and external API
202
+- Workdir outside project support for more flexible file organization
203
+- Agent number tracking in backend and responses for multi-agent identification
204
+- Many bug fixes and stability improvements across the UI, MCP tools, scheduler, uploads, and WebSocket handling
205
+
206
+
207
### v0.9.7 - Projects
208
[Release video](https://youtu.be/RrTDp_v9V1c)
209
- Projects management
@@ -186,8 +222,6 @@ docker run -p 50001:80 agent0ai/agent-zero
222
- More efficient selective streaming for LLMs
223
- UI output length limit improvements
224
189
-
190
-
225
### v0.9.6 - Memory Dashboard
226
[Release video](https://youtu.be/sizjAq2-d9s)
227
- Memory Management Dashboard
@@ -198,7 +232,6 @@ docker run -p 50001:80 agent0ai/agent-zero
232
- LiteLLM retry on temporary errors
233
- Github Copilot provider support
234
201
-
235
### v0.9.5 - Secrets
236
[Release video](https://www.youtube.com/watch?v=VqxUdt7pjd8)
237
- Secrets management - agent can use credentials without seeing them
@@ -242,7 +275,6 @@ docker run -p 50001:80 agent0ai/agent-zero
275
- Docker build support for local images
276
- File browser fix
277
245
-
278
### v0.9.2 - Kokoro TTS, Attachments
279
[Release video](https://www.youtube.com/watch?v=sPot_CAX62I)
280
@@ -250,7 +282,6 @@ docker run -p 50001:80 agent0ai/agent-zero
282
- New message attachments system
283
- Minor updates: log truncation, hyperlink targets, component examples, api cleanup
284
253
-
285
### v0.9.1 - LiteLLM, UI improvements
286
[Release video](https://youtu.be/crwr0M4Spcg)
287
- Langchain replaced with LiteLLM
@@ -267,7 +298,6 @@ docker run -p 50001:80 agent0ai/agent-zero
298
- Streamable HTTP MCP servers support
299
- LLM API URL added to models config for Azure, local and custom providers
300
270
-
301
### v0.9.0 - Agent roles, backup/restore
302
[Release video](https://www.youtube.com/watch?v=rMIe-TC6H-k)
303
- subordinate agents can use prompt profiles for different roles
@@ -314,7 +344,6 @@ Default models set to gpt-4.1
344
345
- **Automatic embedding**
346
317
-
347
### v0.8.3
348
[Release video](https://youtu.be/bPIZo0poalY)
349
docs/README.md
deleted
-90
@@ -1,90 +0,0 @@
1
-
2
-# Agent Zero Documentation
3
-To begin with Agent Zero, follow the links below for detailed guides on various topics:
4
-
5
-- **[Quickstart](quickstart.md):** Launch the UI and run a first task.
6
-- **[Installation](installation.md):** Set up (or [update](installation.md#how-to-update-agent-zero)) Agent Zero on your system.
7
-- **[Usage Guide](usage.md):** Explore GUI features and usage scenarios.
8
-- **[Development](development.md):** Set up a development environment for Agent Zero.
9
-- **[Extensibility](extensibility.md):** Learn how to create custom extensions for Agent Zero.
10
-- **[WebSocket Infrastructure](websocket-infrastructure.md):** Build real-time features with bidirectional handlers and client APIs.
11
-- **[Connectivity](connectivity.md):** Learn how to connect to Agent Zero from other applications.
12
-- **[Architecture Overview](architecture.md):** Understand the internal workings of the framework.
13
-- **[Extensibility](extensibility.md):** Learn how to create custom extensions, tools, instruments, and prompts.
14
-- **[Connectivity](connectivity.md):** Learn how to connect to Agent Zero from other applications.
15
-- **[MCP Setup](mcp_setup.md):** Configure Agent Zero as an MCP client for external tools.
16
-- **[Notifications](notifications.md):** Use the notification system in the UI and backend.
17
-- **[Tunnel](tunnel.md):** Expose your instance securely with Cloudflare tunnels.
18
-- **[Development](development.md):** Set up a development environment for Agent Zero.
19
-- **[Contributing](contribution.md):** Learn how to contribute to the Agent Zero project.
20
-- **[Troubleshooting and FAQ](troubleshooting.md):** Find answers to common issues and questions.
21
-- **[Design Specs](designs/):** Technical specifications for larger features.
22
-
23
-### Your experience with Agent Zero starts now!
24
-
25
-- **Download Agent Zero:** Follow the [installation guide](installation.md) to download and run Agent Zero.
26
-- **Join the Community:** Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community to discuss ideas, ask questions, and collaborate with other contributors.
27
-- **Share your Work:** Share your Agent Zero creations, workflows and discoverings on our [Show and Tell](https://github.com/agent0ai/agent-zero/discussions/categories/show-and-tell) area on GitHub.
28
-- **Report Issues:** Use the [GitHub issue tracker](https://github.com/agent0ai/agent-zero/issues) to report framework-relative bugs or suggest new features.
29
-
30
-## Table of Contents
31
-
32
-- [Welcome to the Agent Zero Documentation](#agent-zero-documentation)
33
- - [Your Experience with Agent Zero](#your-experience-with-agent-zero-starts-now)
34
- - [Table of Contents](#table-of-contents)
35
-- [Installation Guide](installation.md)
36
- - [Windows, macOS and Linux Setup](installation.md#windows-macos-and-linux-setup-guide)
37
- - [Settings Configuration](installation.md#settings-configuration)
38
- - [Choosing Your LLMs](installation.md#choosing-your-llms)
39
- - [Installing and Using Ollama](installation.md#installing-and-using-ollama-local-models)
40
- - [Using Agent Zero on Mobile](installation.md#using-agent-zero-on-your-mobile-device)
41
- - [How to Update Agent Zero](installation.md#how-to-update-agent-zero)
42
- - [Full Binaries Installation](installation.md#in-depth-guide-for-full-binaries-installation)
43
-- [Quickstart](quickstart.md)
44
-- [Usage Guide](usage.md)
45
- - [Basic Operations](usage.md#basic-operations)
46
- - [Restart Framework](usage.md#restart-framework)
47
- - [Action Buttons](usage.md#action-buttons)
48
- - [File Attachments](usage.md#file-attachments)
49
- - [Tool Usage](usage.md#tool-usage)
50
- - [Example of Tools Usage](usage.md#example-of-tools-usage-web-search-and-code-execution)
51
- - [Multi-Agent Cooperation](usage.md#multi-agent-cooperation)
52
- - [Projects](usage.md#projects)
53
- - [Tasks & Scheduling](usage.md#tasks--scheduling)
54
- - [Prompt Engineering](usage.md#prompt-engineering)
55
- - [Secrets & Variables](usage.md#secrets--variables)
56
- - [Voice Interface](usage.md#voice-interface)
57
- - [Mathematical Expressions](usage.md#mathematical-expressions)
58
- - [File Browser](usage.md#file-browser)
59
- - [Backup & Restore](usage.md#backup--restore)
60
-- [Architecture Overview](architecture.md)
61
- - [System Architecture](architecture.md#system-architecture)
62
- - [Runtime Architecture](architecture.md#runtime-architecture)
63
- - [Implementation Details](architecture.md#implementation-details)
64
- - [Core Components](architecture.md#core-components)
65
- - [Agents](architecture.md#1-agents)
66
- - [Tools](architecture.md#2-tools)
67
- - [SearXNG Integration](architecture.md#searxng-integration)
68
- - [Memory System](architecture.md#3-memory-system)
69
- - [Messages History and Summarization](architecture.md#messages-history-and-summarization)
70
- - [Prompts](architecture.md#4-prompts)
71
- - [Knowledge](architecture.md#5-knowledge)
72
- - [Skills](architecture.md#6-skills)
73
- - [Extensions](architecture.md#7-extensions)
74
-- [WebSocket Infrastructure](websocket-infrastructure.md)
75
-- [Development](development.md)
76
- - [Getting Started](contribution.md#getting-started)
77
- - [Making Changes](contribution.md#making-changes)
78
- - [Submitting a Pull Request](contribution.md#submitting-a-pull-request)
79
- - [Documentation Stack](contribution.md#documentation-stack)
80
-- [Troubleshooting and FAQ](troubleshooting.md)
81
- - [Frequently Asked Questions](troubleshooting.md#frequently-asked-questions)
82
- - [Troubleshooting](troubleshooting.md#troubleshooting)
83
-- [Connectivity](connectivity.md)
84
-- [MCP Setup](mcp_setup.md)
85
-- [Notifications](notifications.md)
86
-- [Tunnel](tunnel.md)
87
-- [Development](development.md)
88
-- [Extensibility](extensibility.md)
89
-- [Contributing](contribution.md)
90
-- [Design Specs](designs/)
docs/advanced/architecture.md
renamed
docs/advanced/connectivity.md
renamed
docs/advanced/notifications.md
renamed
docs/advanced/tunneling.md
renamed
docs/advanced/websockets.md
renamed
docs/development/contributing-skills.md
renamed
docs/development/contribution.md
renamed
docs/development/designs/backup-specification-backend.md
renamed
docs/development/designs/backup-specification-frontend.md
renamed
docs/development/extensibility.md
renamed
docs/development/setup.md
renamed
docs/getting-started/installation.md
renamed
+323
-236
@@ -1,250 +1,262 @@
1
-# Users installation guide for Windows, macOS and Linux
1
+# Installation Guide
2
3
Click to open a video to learn how to install Agent Zero:
4
5
-[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
6
-
7
-The following user guide provides instructions for installing and running Agent Zero using Docker, which is the primary runtime environment for the framework. For developers and contributors, we also provide instructions for setting up the [full development environment](#in-depth-guide-for-full-binaries-installation).
8
-
9
-
10
-## Windows, macOS and Linux Setup Guide
11
-
12
-
13
-1. **Install Docker Desktop:**
14
-- Docker Desktop provides the runtime environment for Agent Zero, ensuring consistent behavior and security across platforms
15
-- The entire framework runs within a Docker container, providing isolation and easy deployment
16
-- Available as a user-friendly GUI application for all major operating systems
17
-
18
-1.1. Go to the download page of Docker Desktop [here](https://www.docker.com/products/docker-desktop/). If the link does not work, just search the web for "docker desktop download".
19
-
20
-1.2. Download the version for your operating system. For Windows users, the Intel/AMD version is the main download button.
21
-
22
-<img src="res/setup/image-8.png" alt="docker download" width="200"/>
23
-<br><br>
24
-
25
-> [!NOTE]
26
-> **Linux Users:** You can install either Docker Desktop or docker-ce (Community Edition).
27
-> For Docker Desktop, follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/).
28
-> For docker-ce, follow the instructions [here](https://docs.docker.com/engine/install/).
29
->
30
-> If you're using docker-ce, you'll need to add your user to the `docker` group:
31
-> ```bash
32
-> sudo usermod -aG docker $USER
33
-> ```
34
-> Log out and back in, then run:
35
-> ```bash
36
-> docker login
37
-> ```
38
-
39
-1.3. Run the installer with default settings. On macOS, drag and drop the application to your Applications folder.
40
-
41
-<img src="res/setup/image-9.png" alt="docker install" width="300"/>
42
-<img src="res/setup/image-10.png" alt="docker install" width="300"/>
43
-
44
-<img src="res/setup/image-12.png" alt="docker install" width="300"/>
45
-<br><br>
46
-
47
-1.4. Once installed, launch Docker Desktop:
48
-
49
-<img src="res/setup/image-11.png" alt="docker installed" height="100"/>
50
-<img src="res/setup/image-13.png" alt="docker installed" height="100"/>
51
-<br><br>
5
+[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
6
+
7
+This 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](../development/setup.md).
8
+
9
+## Quick Start Guide
10
+
11
+**Goal:** Go from zero to a first working chat with minimal setup.
12
+
13
+---
14
+
15
+## Step 1: Install Docker Desktop
16
+
17
+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.
18
+
19
+### Choose Your Operating System
20
+
21
+=== "Windows"
22
+
23
+ **1.1. Download Docker Desktop**
24
+
25
+ Go to the [Docker Desktop download page](https://www.docker.com/products/docker-desktop/) and download the Windows version (Intel/AMD is the main download button).
26
+
27
+ <img src="../res/setup/image-8.png" alt="docker download" width="200"/>
28
+ <br><br>
29
+
30
+ **1.2. Run the Installer**
31
+
32
+ Run the installer with default settings.
33
+
34
+ <img src="../res/setup/image-9.png" alt="docker install" width="300"/>
35
+ <img src="../res/setup/image-10.png" alt="docker install" width="300"/>
36
+ <img src="../res/setup/image-12.png" alt="docker install" width="300"/>
37
+ <br><br>
38
+
39
+ **1.3. Launch Docker Desktop**
40
+
41
+ Once installed, launch Docker Desktop from your Start menu or desktop shortcut.
42
+
43
+ <img src="../res/setup/image-11.png" alt="docker installed" height="100"/>
44
+ <img src="../res/setup/image-13.png" alt="docker installed" height="100"/>
45
+ <br><br>
46
+
47
+=== "macOS"
48
+
49
+ **1.1. Download Docker Desktop**
50
+
51
+ Go to the [Docker Desktop download page](https://www.docker.com/products/docker-desktop/) and download the macOS version (choose Apple Silicon or Intel based on your Mac).
52
+
53
+ <img src="../res/setup/image-8.png" alt="docker download" width="200"/>
54
+ <br><br>
55
+
56
+ **1.2. Install Docker Desktop**
57
+
58
+ Drag and drop the Docker application to your Applications folder.
59
+
60
+ <img src="../res/setup/image-9.png" alt="docker install" width="300"/>
61
+ <img src="../res/setup/image-10.png" alt="docker install" width="300"/>
62
+ <img src="../res/setup/image-12.png" alt="docker install" width="300"/>
63
+ <br><br>
64
+
65
+ **1.3. Launch Docker Desktop**
66
+
67
+ Open Docker Desktop from your Applications folder.
68
+
69
+ <img src="../res/setup/image-11.png" alt="docker installed" height="100"/>
70
+ <img src="../res/setup/image-13.png" alt="docker installed" height="100"/>
71
+ <br><br>
72
+
73
+ **1.4. Configure Docker Socket**
74
+
75
+ > [!NOTE]
76
+ > **Important macOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings → Advanced, enable "Allow the default Docker socket to be used (requires password)."
77
+
78
+ 
79
+
80
+=== "Linux"
81
+
82
+ **1.1. Choose Installation Method**
83
+
84
+ You can install either Docker Desktop or docker-ce (Community Edition).
85
+
86
+ **Option A: Docker Desktop (Recommended for beginners)**
87
+
88
+ Follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/).
89
+
90
+ **Option B: docker-ce (Lightweight alternative)**
91
+
92
+ Follow the installation instructions [here](https://docs.docker.com/engine/install/).
93
+
94
+ **1.2. Post-Installation Steps (docker-ce only)**
95
+
96
+ If you installed docker-ce, add your user to the `docker` group:
97
+
98
+ ```bash
99
+ sudo usermod -aG docker $USER
100
+ ```
101
+
102
+ Log out and back in, then authenticate:
103
+
104
+ ```bash
105
+ docker login
106
+ ```
107
+
108
+ **1.3. Launch Docker**
109
+
110
+ If you installed Docker Desktop, launch it from your applications menu.
111
+
112
+ <img src="../res/setup/image-11.png" alt="docker installed" height="100"/>
113
+ <img src="../res/setup/image-13.png" alt="docker installed" height="100"/>
114
+
115
+---
116
+
117
+## Step 2: Run Agent Zero
118
119
> [!NOTE]
54
-> **MacOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings →
55
-> Advanced, enable "Allow the default Docker socket to be used (requires password)."
56
-
57
-
120
+> The Hacker profile is included in the main image. After launch, choose the **hacker** agent profile in Settings if you want the security-focused prompts and tooling.
121
59
-2. **Run Agent Zero:**
122
+### 2.1. Pull the Agent Zero Docker Image
123
61
-- Note: The Hacker profile is included in the main image. After launch, choose the **hacker** agent profile in Settings if you want the security-focused prompts and tooling.
124
+**Using Docker Desktop GUI:**
125
63
-2.1. Pull the Agent Zero Docker image:
126
- Search for `agent0ai/agent-zero` in Docker Desktop
127
- Click the `Pull` button
128
- The image will be downloaded to your machine in a few minutes
129
68
-
69
-
70
-> [!TIP]
71
-> Alternatively, run the following command in your terminal:
72
->
73
-> ```bash
74
-> docker pull agent0ai/agent-zero
75
-> ```
76
-
77
-2.2. OPTIONAL - Map specific folders for persistence:
78
-
79
-> [!CAUTION]
80
-> The recommended persistence and upgrade workflow is to use **Settings → Backup & Restore**.
81
-> Do **not** map the entire `/a0` directory: it contains the application code and can break upgrades.
130
+
131
83
-- Choose or create a directory on your machine where you want to store Agent Zero's data
84
-- This can be any location you prefer (e.g., `C:/agent-zero-data` or `/home/user/agent-zero-data`)
85
-- You can map individual subfolders of `/a0` to a local directory or the full `/a0` directory (not recommended).
86
-- This directory will contain all your Agent Zero files, like the legacy root folder structure:
87
- - `/a0/agents` - Specialized agents with their prompts and tools
88
- - `/a0/memory` or `/a0/knowledge` if you explicitly want to persist those between restarts
89
- - `/a0/knowledge` - Knowledge base
90
- - `/a0/usr/projects` - Project workspaces
91
- - `/a0/usr/skills` - Skills using the open SKILL.md standard
92
- - `/tmp/settings.json` - Your Agent Zero settings
132
+**Using Terminal:**
133
94
-> [!TIP]
95
-> Choose a location that's easy to access and backup. All your Agent Zero data
96
-> will be directly accessible in this directory.
134
+```bash
135
+docker pull agent0ai/agent-zero
136
+```
137
98
-### Automated Configuration via Environment Variables
138
+### 2.2. (Optional) Map Folders for Persistence
139
100
-Agent Zero settings can be automatically configured using environment variables with the `A0_SET_` prefix in your `.env` file. This enables automated deployments without manual configuration.
140
+Choose or create a directory on your machine where you want to store Agent Zero's data. This can be any location you prefer:
141
102
-**Usage:**
103
-Add variables to your `.env` file in the format:
104
-```
105
-A0_SET_{setting_name}={value}
106
-```
142
+- **Windows:** `C:\agent-zero-data`
143
+- **macOS/Linux:** `/home/user/agent-zero-data`
144
108
-**Examples:**
109
-```env
110
-# Model configuration
111
-A0_SET_chat_model_provider=anthropic
112
-A0_SET_chat_model_name=claude-3-5-sonnet-20241022
113
-A0_SET_chat_model_ctx_length=200000
114
-
115
-# Memory settings
116
-A0_SET_memory_recall_enabled=true
117
-A0_SET_memory_recall_interval=5
145
+You can map just the `/a0/usr` directory (recommended) or individual subfolders of `/a0` to a local directory.
146
119
-# Agent configuration
120
-A0_SET_agent_profile=custom
121
-A0_SET_agent_memory_subdir=production
122
-```
147
+> [!CAUTION]
148
+> Do **not** map the entire `/a0` directory: it contains the application code and can break upgrades.
149
124
-**Docker usage:**
125
-When running Docker, you can pass these as environment variables:
126
-```bash
127
-docker run -p 50080:80 \
128
- -e A0_SET_chat_model_provider=anthropic \
129
- -e A0_SET_chat_model_name=claude-3-5-sonnet-20241022 \
130
- agent0ai/agent-zero
131
-```
150
+> [!TIP]
151
+> Choose a location that's easy to access and backup. All your Agent Zero data will be directly accessible in this directory.
152
133
-**Type conversion:**
134
-- Strings are used as-is
135
-- Numbers are automatically converted (e.g., "100000" becomes integer 100000)
136
-- Booleans accept: true/false, 1/0, yes/no, on/off (case-insensitive)
137
-- Dictionaries must be valid JSON (e.g., `{"temperature": "0"}`)
153
+### 2.3. Run the Container
154
139
-**Notes:**
140
-- These provide initial default values when settings.json doesn't exist or when new settings are added to the application. Once a value is saved in settings.json, it takes precedence over these environment variables.
141
-- Sensitive settings (API keys, passwords) use their existing environment variables
142
-- Container/process restart required for changes to take effect
155
+**Using Docker Desktop GUI:**
156
144
-2.3. Run the container:
145
-- In Docker Desktop, go back to the "Images" tab
157
+- In Docker Desktop, go to the "Images" tab
158
- Click the `Run` button next to the `agent0ai/agent-zero` image
159
- Open the "Optional settings" menu
160
- **Ensure at least one host port is mapped to container port `80`** (set host port to `0` for automatic assignment)
161
+- Click the `Run` button
162
150
-Optionally you can map local folders for file persistence:
151
-> [!CAUTION]
152
-> Preferred way of persisting Agent Zero data is to use the backup and restore feature.
153
-> By mapping the whole `/a0` directory to a local directory, you will run into problems when upgrading Agent Zero to a newer version.
154
-- OPTIONAL: Under "Volumes", configure your mapped folders, if needed:
155
- - Example host path: Your chosen directory (e.g., `C:\agent-zero\memory`)
156
- - Example container path: `/a0/memory`
163
+
164
+
165
166
+The container will start and show in the "Containers" tab:
167
159
-- Click the `Run` button in the "Images" tab.
168
+
169
161
-
162
-
170
+**Using Terminal:**
171
164
-- The container will start and show in the "Containers" tab
172
+```bash
173
+docker run -p 0:80 -v /path/to/your/work_dir:/a0/work_dir agent0ai/agent-zero
174
+```
175
166
-
176
+- Replace `0` with a fixed port if you prefer (e.g., `50080:80`)
177
+- Map only the folders you need (e.g., `/a0/work_dir`, `/a0/usr/projects`), not the entire `/a0` directory
178
168
-> [!TIP]
169
-> Alternatively, run the following command in your terminal:
170
-> ```bash
171
-> docker run -p 0:80 -v /path/to/your/work_dir:/a0/work_dir agent0ai/agent-zero
172
-> ```
173
-> - Replace `0` with a fixed port if you prefer (e.g., `50080:80`)
174
-> - Map only the folders you need (e.g., `/a0/work_dir`, `/a0/usr/projects`), not the entire `/a0` directory
179
+### 2.4. Access the Web UI
180
176
-2.4. Access the Web UI:
177
-- The framework will take a few seconds to initialize and the Docker logs will look like the image below.
178
-- 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
181
+The framework will take a few seconds to initialize. Find the mapped port in Docker Desktop (shown as `<PORT>:80`) or click the port right under the container ID:
182
180
-
183
+
184
182
-- Open `http://localhost:<PORT>` in your browser
183
-- The Web UI will open. Agent Zero is ready for configuration!
185
+Open `http://localhost:<PORT>` in your browser. The Web UI will open - Agent Zero is ready for configuration!
186
185
-
187
+
188
189
> [!TIP]
188
-> You can also access the Web UI by clicking the ports right under the container ID in Docker Desktop.
190
+> You can also access the Web UI by clicking the port link directly under the container ID in Docker Desktop.
191
192
> [!NOTE]
191
-> After starting the container, you'll find all Agent Zero files in your chosen
192
-> directory. You can access and edit these files directly on your machine, and
193
-> the changes will be immediately reflected in the running container.
193
+> 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.
194
195
-3. Configure Agent Zero
196
-- Refer to the following sections for a full guide on how to configure Agent Zero.
195
+---
196
198
-## Settings Configuration
199
-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.
197
+## Step 3: Configure Agent Zero
198
+
199
+The UI will show a warning banner "Missing LLM API Key for current settings". Click on `Add your API key` to enter Settings and start configuring A0.
200
+
201
+### Settings Configuration
202
+
203
+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.
204
205
### Agent Configuration
206
+
207
- **Agent Profile:** Select the agent profile (e.g., `agent0`, `hacker`, `researcher`). Profiles can override prompts, tools, and extensions.
208
- **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances.
209
- **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding.
210
211
> [!NOTE]
207
-> Since v0.9.7, custom prompts belong in `/a0/agents/<agent_name>/prompts/` rather than a shared `/prompts` folder. See the [Extensibility guide](extensibility.md#prompts) for details.
212
+> Since v0.9.7, custom prompts belong in `/a0/agents/<agent_name>/prompts/` rather than a shared `/prompts` folder. See the [Extensibility guide](../development/extensibility.md#prompts) for details.
213
209
-
214
+
215
216
### Chat Model Settings
212
-- **Provider:** Select the chat model provider (e.g., Ollama)
213
-- **Model Name:** Choose the specific model (e.g., llama3.2)
214
-- **API URL:** URL of the API endpoint for the chat model - only needed for custom providers like Ollama, Azure, etc.
217
+
218
+- **Provider:** Select the chat model provider (e.g., Anthropic)
219
+- **Model Name:** Choose the specific model (e.g., claude-sonnet-4-5)
220
- **Context Length:** Set the maximum token limit for context window
221
- **Context Window Space:** Configure how much of the context window is dedicated to chat history
222
218
-
223
+
224
220
-> [!IMPORTANT]
221
-> **Model naming is provider-specific.** Use `gpt-4.1` for OpenAI, but use `openai/gpt-4.1` for OpenRouter. If you see “Invalid model ID,” verify the provider and naming format.
225
+**Model naming is provider-specific.**
226
+
227
+Use `claude-sonnet-4-5` for Anthropic, but use `anthropic/claude-sonnet-4-5` for OpenRouter. If you see "Invalid model ID," verify the provider and naming format on the provider website, or search the web for "<name-of-ai-model> model naming".
228
229
> [!TIP]
230
> **Context window tuning:** Set the total context window size first (for example, 100k), then adjust the chat history portion as a fraction of that total. A large fraction on a very large context window can still be enormous.
231
232
+> [!TIP]
233
+> **API URL:** URL of the API endpoint for the chat model - only needed for some providers like Ollama, LM Studio, Azure, etc.
234
+
235
### Utility Model Configuration
236
+
237
- **Provider & Model:** Select a model for utility tasks like memory organization and summarization
238
- **Temperature:** Adjust the determinism of utility responses
239
240
> [!NOTE]
231
-> Utility models need to be strong enough to extract and consolidate memory reliably. Very small models (e.g., 4B) often fail at this; 70B-class models or high-quality cloud “flash/mini” models work best.
241
+> Utility models need to be strong enough to extract and consolidate memory reliably. Very small models (e.g., 4B) often fail at this; 70B-class models or high-quality cloud "flash/mini" models work best.
242
+
243
+### Embedding Model Settings [Optional]
244
233
-### Embedding Model Settings
245
- **Provider:** Choose the embedding model provider (e.g., OpenAI)
246
- **Model Name:** Select the specific embedding model (e.g., text-embedding-3-small)
247
248
> [!NOTE]
238
-> Agent Zero uses a local embedding model by default (tiny footprint), but you can switch to OpenAI embeddings like `text-embedding-3-small` or `text-embedding-3-large` if preferred.
249
+> Agent Zero uses a local embedding model by default (runs on CPU), but you can switch to OpenAI embeddings like `text-embedding-3-small` or `text-embedding-3-large` if preferred.
250
251
### Speech to Text Options
252
+
253
- **Model Size:** Choose the speech recognition model size
254
- **Language Code:** Set the primary language for voice recognition
255
- **Silence Settings:** Configure silence threshold, duration, and timeout parameters for voice input
256
257
### API Keys
246
-- Configure API keys for various service providers directly within the Web UI
247
-- Click `Save` to confirm your settings
258
+
259
+Configure API keys for various service providers directly within the Web UI. Click `Save` to confirm your settings.
260
261
> [!NOTE]
262
> **OpenAI API vs Plus subscription:** A ChatGPT Plus subscription does not include API credits. You must provide a separate API key for OpenAI usage in Agent Zero.
@@ -255,22 +267,20 @@ Agent Zero provides a comprehensive settings interface to customize various aspe
267
> [!CAUTION]
268
> **GitHub Copilot Provider:** When using the GitHub Copilot provider, after selecting the model and entering your first prompt, the OAuth login procedure will begin. You'll find the authentication code and link in the output logs. Complete the authentication process by following the provided link and entering the code, then you may continue using Agent Zero.
269
258
-> [!NOTE]
259
-> **GitHub Copilot Limitations:** GitHub Copilot models typically have smaller rate limits and context windows compared to models hosted by other providers like OpenAI, Anthropic, or Azure. Consider this when working with large conversations or high-frequency requests.
260
-
261
-
262
-
270
### Authentication
271
+
272
- **UI Login:** Set username for web interface access
273
- **UI Password:** Configure password for web interface security
274
- **Root Password:** Manage Docker container root password for SSH access
275
268
-
276
+
277
278
### Development Settings
271
-- **RFC Parameters (local instances only):** configure URLs and ports for remote function calls between instances
279
+
280
+- **RFC Parameters (local instances only):** Configure URLs and ports for remote function calls between instances
281
- **RFC Password:** Configure password for remote function calls
273
-Learn more about Remote Function Calls in the [Development guide](development.md#step-6-configure-ssh-and-rfc-connection).
282
+
283
+Learn more about Remote Function Calls in the [Development guide](../development/setup.md#step-6-configure-ssh-and-rfc-connection).
284
285
> [!IMPORTANT]
286
> Always keep your API keys and passwords secure.
@@ -278,22 +288,28 @@ Learn more about Remote Function Calls in the [Development guide](development.md
288
> [!NOTE]
289
> On Windows host installs (non-Docker), you must use RFC to run shell code on the host system. The Docker runtime handles this automatically.
290
281
-# Choosing Your LLMs
282
-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:
291
+---
292
+
293
+## Choosing Your LLMs
294
+
295
+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:
296
297
| LLM Role | Description |
298
| --- | --- |
299
| `chat_llm` | This is the primary LLM used for conversations and generating responses. |
287
-| `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. |
300
+| `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. |
301
| `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. |
302
303
**How to Change:**
304
+
305
1. Open Settings page in the Web UI.
306
2. Choose the provider for the LLM for each role (Chat model, Utility model, Embedding model) and write the model name.
307
3. Click "Save" to apply the changes.
308
295
-## Important Considerations
296
-### Model Naming by Provider
309
+### Important Considerations
310
+
311
+#### Model Naming by Provider
312
+
313
Use the naming format required by your selected provider:
314
315
| Provider | Model Name Format | Example |
@@ -310,88 +326,105 @@ Use the naming format required by your selected provider:
326
> Venice model parameters can be appended directly to the model name, for example:
327
> `qwen3-235b:disable_thinking=true&include_venice_system_prompt=false`
328
313
-### Context Window & Memory Split
329
+#### Context Window & Memory Split
330
+
331
- Set the **total context window** (e.g., 100k) first.
332
- Then tune the **chat history portion** as a fraction of that total.
333
- Extremely large totals can make even small fractions very large; adjust thoughtfully.
334
318
-### Utility Model Guidance
335
+#### Utility Model Guidance
336
+
337
- Utility models handle summarization and memory extraction.
338
- Very small models (≈4B) usually fail at reliable memory extraction.
321
-- Aim for ~70B class models or strong cloud “flash/mini” models for better results.
339
+- Aim for ~70B class models or strong cloud "flash/mini" models for better results.
340
+
341
+#### Reasoning/Thinking Models
342
323
-### Reasoning/Thinking Models
343
- Reasoning can increase cost and latency. Some models perform better **without** reasoning.
344
- If a model supports it, disable reasoning via provider-specific parameters (e.g., Venice `disable_thinking=true`).
345
346
+---
347
+
348
## Installing and Using Ollama (Local Models)
328
-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:
349
330
-#### First step: installation
331
-**On Windows:**
350
+Ollama is a powerful tool that allows you to run various large language models locally.
351
333
-Download Ollama from the official website and install it on your machine.
352
+### Installation
353
335
-<button>[Download Ollama Setup](https://ollama.com/download/OllamaSetup.exe)</button>
354
+=== "Windows"
355
337
-**On macOS:**
338
-```
339
-brew install ollama
340
-```
341
-Otherwise choose macOS installer from the [official website](https://ollama.com/).
356
+ Download and install Ollama from the official website:
357
+
358
+ <button>[Download Ollama Setup](https://ollama.com/download/OllamaSetup.exe)</button>
359
343
-**On Linux:**
344
-```bash
345
-curl -fsSL https://ollama.com/install.sh | sh
346
-```
360
+=== "macOS"
361
+
362
+ **Using Homebrew:**
363
+
364
+ ```bash
365
+ brew install ollama
366
+ ```
367
+
368
+ **Using Installer:**
369
+
370
+ Download from the [official website](https://ollama.com/).
371
+
372
+=== "Linux"
373
+
374
+ Run the installation script:
375
+
376
+ ```bash
377
+ curl -fsSL https://ollama.com/install.sh | sh
378
+ ```
379
+
380
+### Pulling Models
381
382
**Finding Model Names:**
383
+
384
Visit the [Ollama model library](https://ollama.com/library) for a list of available models and their corresponding names. Ollama models are referenced by **model name only** (for example, `llama3.2`).
385
351
-#### Second step: pulling the model
352
-**On Windows, macOS, and Linux:**
353
-```
386
+**Pull a model:**
387
+
388
+```bash
389
ollama pull <model-name>
390
```
391
357
-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`.
358
-
359
-2. A CLI message should confirm the model download on your system
392
+Replace `<model-name>` with the name of the model you want to use. For example: `ollama pull mistral-large`
393
361
-#### Selecting your model within Agent Zero
362
-1. Once you've downloaded your model(s), you must select it in the Settings page of the GUI.
363
-
364
-2. Within the Chat model, Utility model, or Embedding model section, choose Ollama as provider.
394
+### Configuring Ollama in Agent Zero
395
396
+1. Once you've downloaded your model(s), select it in the Settings page of the GUI.
397
+2. Within the Chat model, Utility model, or Embedding model section, choose **Ollama** as provider.
398
3. Write your model code as expected by Ollama, in the format `llama3.2` or `qwen2.5:7b`
367
-
368
-4. Provide your API base URL to your ollama API endpoint, usually `http://host.docker.internal:11434`
369
-
399
+4. Provide your API base URL to your Ollama API endpoint, usually `http://host.docker.internal:11434`
400
5. Click `Save` to confirm your settings.
401
372
-
402
+
403
404
> [!NOTE]
405
> If Agent Zero runs in Docker and Ollama runs on the host, ensure port **11434** is reachable from the container. If both services are in the same Docker network, you can use `http://<container_name>:11434` instead of `host.docker.internal`.
406
377
-#### Managing your downloaded models
378
-Once you've downloaded some models, you might want to check which ones you have available or remove any you no longer need.
407
+### Managing Downloaded Models
408
380
-- **Listing downloaded models:**
381
- To see a list of all the models you've downloaded, use the command:
382
- ```
383
- ollama list
384
- ```
385
-- **Removing a model:**
386
- If you need to remove a downloaded model, you can use the `ollama rm` command followed by the model name:
387
- ```
388
- ollama rm <model-name>
389
- ```
409
+**Listing downloaded models:**
410
+
411
+```bash
412
+ollama list
413
+```
414
415
+**Removing a model:**
416
+
417
+```bash
418
+ollama rm <model-name>
419
+```
420
+
421
+> [!TIP]
422
+> 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.
423
392
-- 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.
424
+---
425
+
426
+## Using Agent Zero on Your Mobile Device
427
394
-## Using Agent Zero on your mobile device
428
Agent Zero's Web UI is accessible from any device on your network through the Docker container:
429
430
> [!NOTE]
@@ -412,19 +445,21 @@ Agent Zero's Web UI is accessible from any device on your network through the Do
445
> - The port is automatically assigned by Docker unless you specify one
446
447
> [!NOTE]
415
-> If you're running Agent Zero directly on your system (legacy approach) instead of
416
-> using Docker, configure the bind address/ports via flags or environment variables:
448
+> If you're running Agent Zero directly on your system (legacy approach) instead of using Docker, configure the bind address/ports via flags or environment variables:
449
> - Use `--host 0.0.0.0` (or set `WEB_UI_HOST=0.0.0.0` in `.env`) to listen on all interfaces.
450
> - Use `--port <PORT>` (or `WEB_UI_PORT`) to pick the HTTP port.
451
420
-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).
452
+For developers or users who need to run Agent Zero directly on their system, see the [In-Depth Guide for Full Binaries Installation](../development/setup.md).
453
+
454
+---
455
422
-# How to update Agent Zero
456
+## How to Update Agent Zero
457
458
> [!NOTE]
459
> Since v0.9, Agent Zero includes a Backup & Restore workflow in the Settings UI. This is the **safest** way to upgrade Docker instances.
460
427
-## Recommended Update Process (Docker)
461
+### Recommended Update Process (Docker)
462
+
463
1. **Keep the old container running** and note its port.
464
2. **Pull the new image** (`agent0ai/agent-zero:latest`).
465
3. **Start a new container** on a different host port.
@@ -435,8 +470,10 @@ For developers or users who need to run Agent Zero directly on their system,see
470
> [!TIP]
471
> If the new instance fails to load settings, remove `/a0/tmp/settings.json` and restart to regenerate defaults.
472
438
-## Manual Migration (Legacy or Non-Docker)
473
+### Manual Migration (Legacy or Non-Docker)
474
+
475
If you are migrating from older, non-Docker setups, copy these directories into your new instance:
476
+
477
- `/a0/memory` (agent memories)
478
- `/a0/knowledge` (custom knowledge)
479
- `/a0/instruments` (custom instruments)
@@ -446,8 +483,58 @@ If you are migrating from older, non-Docker setups, copy these directories into
483
484
Then proceed with the Docker installation steps above.
485
486
+---
487
+
488
+## Advanced: Automated Configuration via Environment Variables
489
+
490
+Agent Zero settings can be automatically configured using environment variables with the `A0_SET_` prefix in your `.env` file. This enables automated deployments without manual configuration.
491
+
492
+**Usage:**
493
+
494
+Add variables to your `.env` file in the format:
495
+
496
+```env
497
+A0_SET_{setting_name}={value}
498
+```
499
+
500
+**Examples:**
501
+
502
+```env
503
+# Model configuration
504
+A0_SET_chat_model_provider=anthropic
505
+A0_SET_chat_model_name=claude-3-5-sonnet-20241022
506
+A0_SET_chat_model_ctx_length=200000
507
+
508
+# Memory settings
509
+A0_SET_memory_recall_enabled=true
510
+A0_SET_memory_recall_interval=5
511
+
512
+# Agent configuration
513
+A0_SET_agent_profile=custom
514
+A0_SET_agent_memory_subdir=production
515
+```
516
+
517
+**Docker usage:**
518
+
519
+When running Docker, you can pass these as environment variables:
520
+
521
+```bash
522
+docker run -p 50080:80 \
523
+ -e A0_SET_chat_model_provider=anthropic \
524
+ -e A0_SET_chat_model_name=claude-3-5-sonnet-20241022 \
525
+ agent0ai/agent-zero
526
+```
527
+
528
+**Notes:**
529
+
530
+- These provide initial default values when settings.json doesn't exist or when new settings are added to the application. Once a value is saved in settings.json, it takes precedence over these environment variables.
531
+- Sensitive settings (API keys, passwords) use their existing environment variables
532
+- Container/process restart required for changes to take effect
533
+
534
+---
535
+
536
+## Conclusion
537
450
-### Conclusion
538
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.
539
453
-If you encounter any issues during the installation process, please consult the [Troubleshooting section](troubleshooting.md) of this documentation or refer to the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community for assistance.
540
+If you encounter any issues during the installation process, please consult the [Troubleshooting section](../guides/troubleshooting.md) of this documentation or refer to the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community for assistance.
docs/getting-started/mcp-setup.md
renamed
docs/getting-started/vps-deployment.md
new
+768
@@ -0,0 +1,768 @@
1
+# Agent Zero Installation Guide
2
+
3
+> **Purpose:** Step-by-step guide for deploying Agent Zero instances on VPS/dedicated servers
4
+> **Author:** Auto-generated from deployment experience
5
+> **Last Updated:** December 21 2025
6
+> **Compatibility:** Docker-capable Linux servers (AlmaLinux, CentOS, Rocky, Ubuntu, Debian)
7
+
8
+---
9
+
10
+## Table of Contents
11
+
12
+1. [Prerequisites](#prerequisites)
13
+2. [Docker Installation](#docker-installation)
14
+3. [Agent Zero Container Deployment](#agent-zero-container-deployment)
15
+4. [Apache Reverse Proxy Configuration](#apache-reverse-proxy-configuration)
16
+5. [SSL/TLS Configuration](#ssltls-configuration)
17
+6. [Authentication Setup](#authentication-setup)
18
+7. [Domain & DNS Setup](#domain--dns-setup)
19
+8. [Verification & Testing](#verification--testing)
20
+9. [Troubleshooting](#troubleshooting)
21
+10. [Maintenance & Updates](#maintenance--updates)
22
+11. [Quick Reference](#quick-reference)
23
+
24
+---
25
+
26
+## Prerequisites
27
+
28
+### Server Requirements
29
+
30
+| Requirement | Minimum | Recommended |
31
+|-------------|---------|-------------|
32
+| **RAM** | 2 GB | 4+ GB |
33
+| **Storage** | 20 GB | 50+ GB |
34
+| **CPU** | 1 vCPU | 2+ vCPU |
35
+| **OS** | Linux (64-bit) | AlmaLinux 9, Ubuntu 22.04+ |
36
+| **Network** | Static IP | Dedicated IP with reverse DNS |
37
+
38
+### Required Access
39
+
40
+- Root or sudo access to the server
41
+- SSH access (preferably on non-standard port)
42
+- Domain/subdomain with DNS control
43
+- SSL certificate (Let's Encrypt or commercial)
44
+
45
+### Software Dependencies
46
+
47
+- Docker Engine 24.0+
48
+- Apache 2.4+ with mod_proxy, mod_proxy_http, mod_proxy_wstunnel, mod_ssl, mod_rewrite
49
+- curl, git (optional)
50
+
51
+---
52
+
53
+## Docker Installation
54
+
55
+### Method A: Debian/Ubuntu Systems
56
+
57
+```bash
58
+# Update package index
59
+apt-get update
60
+
61
+# Install prerequisites
62
+apt-get install -y ca-certificates curl gnupg
63
+
64
+# Add Docker's official GPG key
65
+install -m 0755 -d /etc/apt/keyrings
66
+curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
67
+chmod a+r /etc/apt/keyrings/docker.gpg
68
+
69
+# Set up repository
70
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
71
+
72
+# Install Docker
73
+apt-get update
74
+apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
75
+
76
+# Start and enable Docker
77
+systemctl enable docker
78
+systemctl start docker
79
+```
80
+
81
+### Method B: AlmaLinux/Rocky/CentOS/RHEL Systems
82
+
83
+```bash
84
+# Install required packages
85
+dnf -y install dnf-plugins-core
86
+
87
+# Add Docker repository (use CentOS repo for AlmaLinux/Rocky)
88
+dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
89
+
90
+# Install Docker
91
+dnf -y install docker-ce docker-ce-cli containerd.io docker-compose-plugin
92
+
93
+# Start and enable Docker
94
+systemctl enable docker
95
+systemctl start docker
96
+```
97
+
98
+### Method C: Generic (Convenience Script)
99
+
100
+> ⚠️ **Note:** May not work on all distributions (e.g., AlmaLinux)
101
+
102
+```bash
103
+curl -fsSL https://get.docker.com -o get-docker.sh
104
+sh get-docker.sh
105
+systemctl enable docker
106
+systemctl start docker
107
+```
108
+
109
+### Verify Docker Installation
110
+
111
+```bash
112
+docker --version
113
+docker run hello-world
114
+```
115
+
116
+---
117
+
118
+## Agent Zero Container Deployment
119
+
120
+### Step 1: Create Directory Structure
121
+
122
+```bash
123
+# Choose your installation path
124
+A0_NAME="a0-instance" # Change this to your instance name
125
+A0_PATH="/opt/${A0_NAME}"
126
+
127
+# Create directories
128
+mkdir -p ${A0_PATH}
129
+mkdir -p ${A0_PATH}/work_dir
130
+mkdir -p ${A0_PATH}/memory
131
+mkdir -p ${A0_PATH}/logs
132
+```
133
+
134
+### Step 2: Create Environment Configuration
135
+
136
+```bash
137
+# Create .env file with authentication
138
+cat > ${A0_PATH}/.env << 'EOF'
139
+# Agent Zero Configuration
140
+# Authentication (REQUIRED for web access)
141
+AUTH_LOGIN=your_username_here
142
+AUTH_PASSWORD=your_secure_password_here
143
+
144
+# Optional: Additional configuration
145
+# See Agent Zero documentation for all options
146
+EOF
147
+```
148
+
149
+> ⚠️ **CRITICAL:** `AUTH_LOGIN` is the **username**, not a boolean!
150
+> - ✅ Correct: `AUTH_LOGIN=admin`
151
+> - ❌ Wrong: `AUTH_LOGIN=true`
152
+
153
+### Step 3: Choose Host Port
154
+
155
+| Port | Use Case |
156
+|------|----------|
157
+| `50080` | Standard/recommended for reverse proxy setups |
158
+| `50081`, `50082`... | Additional instances on same server |
159
+| `80` | Direct access (not recommended for production) |
160
+
161
+### Step 4: Pull and Run Container
162
+
163
+```bash
164
+# Set variables
165
+A0_NAME="a0-instance"
166
+A0_PATH="/opt/${A0_NAME}"
167
+A0_PORT="50080"
168
+
169
+# Pull latest image
170
+docker pull agent0ai/agent-zero:latest
171
+
172
+# Run container
173
+docker run -d --name ${A0_NAME} --restart unless-stopped -p ${A0_PORT}:80 -v ${A0_PATH}/.env:/a0/.env -v ${A0_PATH}/work_dir:/a0/work_dir -v ${A0_PATH}/memory:/a0/memory -v ${A0_PATH}/logs:/a0/logs agent0ai/agent-zero:latest
174
+```
175
+
176
+### Step 5: Verify Container
177
+
178
+```bash
179
+# Check container is running
180
+docker ps | grep ${A0_NAME}
181
+
182
+# Check logs
183
+docker logs ${A0_NAME}
184
+
185
+# Test local access
186
+curl -I http://127.0.0.1:${A0_PORT}/
187
+```
188
+
189
+Expected response: `HTTP/1.1 302 FOUND` with `Location: /login` (if auth enabled)
190
+
191
+---
192
+
193
+## Apache Reverse Proxy Configuration
194
+
195
+### Required Apache Modules
196
+
197
+```bash
198
+# Debian/Ubuntu
199
+a2enmod proxy proxy_http proxy_wstunnel ssl rewrite headers
200
+systemctl restart apache2
201
+
202
+# AlmaLinux/CentOS (usually pre-loaded)
203
+httpd -M | grep -E "proxy|rewrite|ssl"
204
+```
205
+
206
+### Configuration for Standard Apache (Debian/Ubuntu)
207
+
208
+Create `/etc/apache2/sites-available/a0-instance.conf`:
209
+
210
+```apache
211
+# Agent Zero Reverse Proxy Configuration
212
+# Instance: a0-instance
213
+# Domain: a0.example.com
214
+
215
+# HTTP - Redirect to HTTPS
216
+<VirtualHost *:80>
217
+ ServerName a0.example.com
218
+ ServerAlias www.a0.example.com
219
+
220
+ RewriteEngine On
221
+ RewriteCond %{HTTPS} off
222
+ RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
223
+</VirtualHost>
224
+
225
+# HTTPS - Proxy to Container
226
+<VirtualHost *:443>
227
+ ServerName a0.example.com
228
+ ServerAlias www.a0.example.com
229
+ ServerAdmin webmaster@example.com
230
+
231
+ # SSL Configuration
232
+ SSLEngine on
233
+ SSLCertificateFile /path/to/certificate.crt
234
+ SSLCertificateKeyFile /path/to/private.key
235
+ SSLCertificateChainFile /path/to/chain.crt
236
+
237
+ # Proxy Configuration
238
+ ProxyPreserveHost On
239
+ ProxyPass / http://127.0.0.1:50080/
240
+ ProxyPassReverse / http://127.0.0.1:50080/
241
+
242
+ # WebSocket Support (Required for real-time features)
243
+ RewriteEngine On
244
+ RewriteCond %{HTTP:Upgrade} websocket [NC]
245
+ RewriteCond %{HTTP:Connection} upgrade [NC]
246
+ RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L]
247
+
248
+ # Logging
249
+ ErrorLog ${APACHE_LOG_DIR}/a0-instance.error.log
250
+ CustomLog ${APACHE_LOG_DIR}/a0-instance.access.log combined
251
+</VirtualHost>
252
+```
253
+
254
+Enable and restart:
255
+
256
+```bash
257
+a2ensite a0-instance.conf
258
+apache2ctl configtest
259
+systemctl reload apache2
260
+```
261
+
262
+### Configuration for DirectAdmin Apache (AlmaLinux/CentOS)
263
+
264
+#### Option A: Use httpd-includes.conf (Recommended)
265
+
266
+Edit `/etc/httpd/conf/extra/httpd-includes.conf`:
267
+
268
+```apache
269
+# Agent Zero Proxy Configuration
270
+# Instance: a0-instance
271
+# Domain: a0.example.com
272
+# Note: Use specific IP, not wildcards, for DirectAdmin compatibility
273
+
274
+<VirtualHost YOUR_SERVER_IP:80>
275
+ ServerName a0.example.com
276
+ ServerAlias www.a0.example.com
277
+
278
+ RewriteEngine On
279
+ RewriteCond %{HTTPS} off
280
+ RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
281
+</VirtualHost>
282
+
283
+<VirtualHost YOUR_SERVER_IP:443>
284
+ ServerName a0.example.com
285
+ ServerAlias www.a0.example.com
286
+ ServerAdmin webmaster@example.com
287
+
288
+ SSLEngine on
289
+ # DirectAdmin SSL cert paths (adjust user and domain)
290
+ SSLCertificateFile /usr/local/directadmin/data/users/USERNAME/domains/example.com.cert.combined
291
+ SSLCertificateKeyFile /usr/local/directadmin/data/users/USERNAME/domains/example.com.key
292
+
293
+ ProxyPreserveHost On
294
+ ProxyPass / http://127.0.0.1:50080/
295
+ ProxyPassReverse / http://127.0.0.1:50080/
296
+
297
+ # WebSocket Support
298
+ RewriteEngine On
299
+ RewriteCond %{HTTP:Upgrade} websocket [NC]
300
+ RewriteCond %{HTTP:Connection} upgrade [NC]
301
+ RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L]
302
+
303
+ ErrorLog /var/log/httpd/domains/a0.example.com.error.log
304
+ CustomLog /var/log/httpd/domains/a0.example.com.access.log combined
305
+</VirtualHost>
306
+```
307
+
308
+> ⚠️ **Important for DirectAdmin:**
309
+> - Use **specific IP address** (e.g., `192.168.1.100:443`), not `*:443`
310
+> - IP-bound vhosts take precedence over DirectAdmin's vhosts
311
+> - SSL certs are in `/usr/local/directadmin/data/users/USERNAME/domains/`
312
+
313
+#### Option B: Standalone conf.d file
314
+
315
+If `/etc/httpd/conf.d/` is included in your Apache config:
316
+
317
+```bash
318
+# Check if conf.d is included
319
+grep 'conf.d' /etc/httpd/conf/httpd.conf
320
+
321
+# If not, add before directadmin-vhosts.conf include:
322
+sed -i '/Include conf\/extra\/directadmin-vhosts.conf/i Include conf.d/*.conf' /etc/httpd/conf/httpd.conf
323
+
324
+# Create config
325
+mkdir -p /etc/httpd/conf.d
326
+cat > /etc/httpd/conf.d/httpd-vhosts-a0.conf << 'EOF'
327
+# Your vhost config here (same as Option A)
328
+EOF
329
+```
330
+
331
+### Verify and Restart Apache
332
+
333
+```bash
334
+# Test configuration
335
+httpd -t # AlmaLinux/CentOS
336
+apachectl -t # Alternative
337
+apache2ctl -t # Debian/Ubuntu
338
+
339
+# Restart
340
+systemctl restart httpd # AlmaLinux/CentOS
341
+systemctl restart apache2 # Debian/Ubuntu
342
+```
343
+
344
+---
345
+
346
+## SSL/TLS Configuration
347
+
348
+### Option A: Let's Encrypt with Certbot
349
+
350
+```bash
351
+# Install Certbot
352
+# Debian/Ubuntu:
353
+apt-get install certbot python3-certbot-apache
354
+
355
+# AlmaLinux/CentOS:
356
+dnf install certbot python3-certbot-apache
357
+
358
+# Obtain certificate
359
+certbot --apache -d a0.example.com -d www.a0.example.com
360
+
361
+# Auto-renewal (usually automatic, but verify)
362
+certbot renew --dry-run
363
+```
364
+
365
+### Option B: DirectAdmin Auto-SSL
366
+
367
+If using DirectAdmin, SSL is typically managed automatically:
368
+
369
+1. Create domain/subdomain in DirectAdmin
370
+2. Enable "SSL" for the domain
371
+3. DirectAdmin will obtain Let's Encrypt certificate
372
+4. Certs stored in `/usr/local/directadmin/data/users/USERNAME/domains/`
373
+
374
+### Option C: Manual/Commercial Certificates
375
+
376
+Place certificates in secure location:
377
+
378
+```bash
379
+mkdir -p /etc/ssl/a0
380
+chmod 700 /etc/ssl/a0
381
+
382
+# Copy your certificates
383
+cp certificate.crt /etc/ssl/a0/
384
+cp private.key /etc/ssl/a0/
385
+cp chain.crt /etc/ssl/a0/ # if applicable
386
+
387
+chmod 600 /etc/ssl/a0/*
388
+```
389
+
390
+---
391
+
392
+## Authentication Setup
393
+
394
+### Understanding A0 Authentication Variables
395
+
396
+| Variable | Purpose | Example |
397
+|----------|---------|--------|
398
+| `AUTH_LOGIN` | The **username** for login | `AUTH_LOGIN=admin` |
399
+| `AUTH_PASSWORD` | The **password** for login | `AUTH_PASSWORD=SecurePass123!` |
400
+
401
+> ⚠️ **Common Mistake:** `AUTH_LOGIN` is the username, **not** a boolean to enable auth!
402
+
403
+### Setting Up Authentication
404
+
405
+```bash
406
+# Edit .env file
407
+vi /opt/a0-instance/.env
408
+
409
+# Add/update these lines:
410
+AUTH_LOGIN=your_username
411
+AUTH_PASSWORD=your_secure_password
412
+
413
+# Restart container to apply
414
+docker restart a0-instance
415
+```
416
+
417
+### Password Requirements
418
+
419
+- Minimum 8 characters recommended
420
+- Special characters are supported (properly escaped)
421
+- Avoid these characters in passwords: `' " \` $ \` (or escape carefully)
422
+
423
+### Disabling Authentication (Not Recommended)
424
+
425
+To disable authentication (local/dev use only):
426
+
427
+```bash
428
+# Remove or comment out both lines in .env:
429
+# AUTH_LOGIN=
430
+# AUTH_PASSWORD=
431
+
432
+docker restart a0-instance
433
+```
434
+
435
+---
436
+
437
+## Domain & DNS Setup
438
+
439
+### DNS Configuration
440
+
441
+Create an A record pointing to your server:
442
+
443
+| Type | Name | Value | TTL |
444
+|------|------|-------|-----|
445
+| A | a0 | YOUR_SERVER_IP | 300 |
446
+| A | www.a0 | YOUR_SERVER_IP | 300 |
447
+
448
+### DirectAdmin Subdomain Setup
449
+
450
+1. Log into DirectAdmin
451
+2. Navigate to: **Domain Setup** → Select domain → **Subdomain Management**
452
+3. Create subdomain (e.g., `a0`)
453
+4. Note: You'll override the DocumentRoot with Apache proxy config
454
+
455
+### Verify DNS Propagation
456
+
457
+```bash
458
+# Check DNS resolution
459
+dig a0.example.com +short
460
+nslookup a0.example.com
461
+
462
+# Should return your server IP
463
+```
464
+
465
+---
466
+
467
+## Verification & Testing
468
+
469
+### Step-by-Step Verification Checklist
470
+
471
+```bash
472
+# 1. Verify Docker container is running
473
+docker ps | grep a0-instance
474
+
475
+# 2. Check container logs for errors
476
+docker logs a0-instance --tail 50
477
+
478
+# 3. Test local container access
479
+curl -I http://127.0.0.1:50080/
480
+# Expected: HTTP/1.1 302 FOUND, Location: /login
481
+
482
+# 4. Test Apache config
483
+httpd -t # or apache2ctl -t
484
+
485
+# 5. Check Apache is proxying correctly
486
+curl -I http://127.0.0.1:80 -H "Host: a0.example.com"
487
+curl -Ik https://127.0.0.1:443 -H "Host: a0.example.com"
488
+
489
+# 6. Test external HTTPS access
490
+curl -I https://a0.example.com/
491
+# Expected: HTTP/2 302 with Location: /login
492
+
493
+# 7. Test login page loads
494
+curl -s https://a0.example.com/login | grep -i "<title>"
495
+# Expected: <title>Login - Agent Zero</title>
496
+```
497
+
498
+### WebSocket Verification
499
+
500
+```bash
501
+# Install wscat if needed
502
+npm install -g wscat
503
+
504
+# Test WebSocket connection
505
+wscat -c wss://a0.example.com/ws
506
+```
507
+
508
+---
509
+
510
+## Troubleshooting
511
+
512
+### Issue: "Invalid Credentials" on Login
513
+
514
+**Cause:** Incorrect `.env` configuration
515
+
516
+**Fix:**
517
+```bash
518
+# Verify .env inside container
519
+docker exec a0-instance cat /a0/.env
520
+
521
+# Ensure format is:
522
+# AUTH_LOGIN=username (NOT AUTH_LOGIN=true)
523
+# AUTH_PASSWORD=password
524
+
525
+# Restart after fixing
526
+docker restart a0-instance
527
+```
528
+
529
+### Issue: 403 Forbidden
530
+
531
+**Cause:** DirectAdmin vhost overriding custom proxy config
532
+
533
+**Fix:**
534
+```bash
535
+# Check vhost order
536
+httpd -S 2>&1 | grep your-domain
537
+
538
+# Ensure custom config loads BEFORE directadmin-vhosts.conf
539
+# Use specific IP binding (e.g., 192.168.1.1:443) not wildcards (*:443)
540
+
541
+# Restart Apache
542
+systemctl restart httpd
543
+```
544
+
545
+### Issue: 502 Bad Gateway
546
+
547
+**Cause:** Container not running or wrong port
548
+
549
+**Fix:**
550
+```bash
551
+# Check container status
552
+docker ps -a | grep a0-instance
553
+
554
+# If stopped, check logs
555
+docker logs a0-instance
556
+
557
+# Restart container
558
+docker start a0-instance
559
+
560
+# Verify port binding
561
+netstat -tlnp | grep 50080
562
+```
563
+
564
+### Issue: 504 Gateway Timeout
565
+
566
+**Cause:** Container overloaded or unresponsive
567
+
568
+**Fix:**
569
+```bash
570
+# Check container resource usage
571
+docker stats a0-instance --no-stream
572
+
573
+# Restart container
574
+docker restart a0-instance
575
+
576
+# Check for memory issues
577
+free -h
578
+```
579
+
580
+### Issue: WebSocket Connection Failed
581
+
582
+**Cause:** Missing WebSocket proxy rules
583
+
584
+**Fix:**
585
+Ensure these lines are in your vhost config:
586
+
587
+```apache
588
+RewriteEngine On
589
+RewriteCond %{HTTP:Upgrade} websocket [NC]
590
+RewriteCond %{HTTP:Connection} upgrade [NC]
591
+RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L]
592
+```
593
+
594
+### Issue: Container Won't Start
595
+
596
+**Cause:** Port conflict or Docker issue
597
+
598
+**Fix:**
599
+```bash
600
+# Check what's using the port
601
+netstat -tlnp | grep 50080
602
+
603
+# Remove conflicting container
604
+docker rm -f conflicting-container
605
+
606
+# Check Docker daemon
607
+systemctl status docker
608
+journalctl -u docker --since "1 hour ago"
609
+```
610
+
611
+### Issue: Changes to .env Not Taking Effect
612
+
613
+**Cause:** Container needs restart to reload env
614
+
615
+**Fix:**
616
+```bash
617
+docker restart a0-instance
618
+
619
+# Verify env is loaded
620
+docker exec a0-instance cat /a0/.env
621
+```
622
+
623
+---
624
+
625
+## Maintenance & Updates
626
+
627
+### Updating Agent Zero
628
+
629
+```bash
630
+# Pull latest image
631
+docker pull agent0ai/agent-zero:latest
632
+
633
+# Stop and remove old container (data persists in volumes)
634
+docker stop a0-instance
635
+docker rm a0-instance
636
+
637
+# Recreate with same settings
638
+docker run -d --name a0-instance --restart unless-stopped -p 50080:80 -v /opt/a0-instance/.env:/a0/.env -v /opt/a0-instance/work_dir:/a0/work_dir -v /opt/a0-instance/memory:/a0/memory -v /opt/a0-instance/logs:/a0/logs agent0ai/agent-zero:latest
639
+```
640
+
641
+### Backup Strategy
642
+
643
+```bash
644
+# Backup all instance data
645
+tar -czvf a0-backup-$(date +%Y%m%d).tar.gz /opt/a0-instance/
646
+
647
+# Key items to backup:
648
+# - /opt/a0-instance/.env (configuration)
649
+# - /opt/a0-instance/memory/ (agent memories)
650
+# - /opt/a0-instance/work_dir/ (working files)
651
+```
652
+
653
+### Monitoring
654
+
655
+```bash
656
+# Check container health
657
+docker ps --format "table {{.Names}} {{.Status}} {{.Ports}}"
658
+
659
+# View recent logs
660
+docker logs --tail 100 -f a0-instance
661
+
662
+# Resource usage
663
+docker stats a0-instance
664
+```
665
+
666
+### Docker Cleanup
667
+
668
+```bash
669
+# Remove unused images
670
+docker image prune -f
671
+
672
+# Remove all unused Docker resources
673
+docker system prune -f
674
+```
675
+
676
+---
677
+
678
+## Quick Reference
679
+
680
+### Essential Commands
681
+
682
+```bash
683
+# Container Management
684
+docker start a0-instance
685
+docker stop a0-instance
686
+docker restart a0-instance
687
+docker logs a0-instance
688
+docker exec -it a0-instance bash
689
+
690
+# Apache Management
691
+systemctl restart httpd # RHEL/AlmaLinux
692
+systemctl restart apache2 # Debian/Ubuntu
693
+httpd -t # Test config
694
+
695
+# Quick Diagnostics
696
+docker ps | grep a0
697
+curl -I https://your-domain.com/login
698
+```
699
+
700
+### Standard Paths
701
+
702
+| Component | Path |
703
+|-----------|----- |
704
+| Instance Data | `/opt/a0-instance/` |
705
+| Environment File | `/opt/a0-instance/.env` |
706
+| Memory Storage | `/opt/a0-instance/memory/` |
707
+| Work Directory | `/opt/a0-instance/work_dir/` |
708
+| Logs | `/opt/a0-instance/logs/` |
709
+| Apache Config (Standard) | `/etc/apache2/sites-available/` |
710
+| Apache Config (DirectAdmin) | `/etc/httpd/conf/extra/httpd-includes.conf` |
711
+| DirectAdmin SSL Certs | `/usr/local/directadmin/data/users/USER/domains/` |
712
+
713
+### Standard Ports
714
+
715
+| Port | Purpose |
716
+|------|---------|
717
+| 50080 | First A0 instance |
718
+| 50081 | Second A0 instance |
719
+| 50082 | Third A0 instance |
720
+| 80 | HTTP (redirect to HTTPS) |
721
+| 443 | HTTPS (main access) |
722
+
723
+### .env Template
724
+
725
+```bash
726
+# Agent Zero Configuration Template
727
+# Copy and customize for each instance
728
+
729
+# Authentication (REQUIRED for production)
730
+AUTH_LOGIN=your_username
731
+AUTH_PASSWORD=your_secure_password
732
+
733
+# Optional: Additional settings
734
+# Refer to Agent Zero documentation for all options
735
+```
736
+
737
+---
738
+
739
+## Appendix: Multi-Instance Setup
740
+
741
+For running multiple A0 instances on the same server:
742
+
743
+```bash
744
+# Instance 1: a0-primary on port 50080
745
+mkdir -p /opt/a0-primary
746
+# ... create .env, run container on port 50080
747
+
748
+# Instance 2: a0-dev on port 50081
749
+mkdir -p /opt/a0-dev
750
+# ... create .env, run container on port 50081
751
+
752
+# Instance 3: a0-backup on port 50082
753
+mkdir -p /opt/a0-backup
754
+# ... create .env, run container on port 50082
755
+```
756
+
757
+Each instance needs:
758
+- Unique container name
759
+- Unique host port
760
+- Separate data directory
761
+- Separate domain/subdomain
762
+- Separate Apache vhost config
763
+
764
+---
765
+
766
+*This guide comes from successful Agent Zero deployments across DirectAdmin and standard Linux environments.*
767
+
768
+Contributed by @hurtdidit in the A0 Community.
docs/guides/troubleshooting.md
renamed
docs/guides/usage.md
renamed
+20
-20
@@ -1,7 +1,7 @@
1
# Usage Guide
2
This guide explores usage and configuration scenarios for Agent Zero. You can consider this as a reference post-installation guide.
3
4
-
4
+
5
6
## Basic Operations
7
Agent Zero provides several basic operations through its interface:
@@ -9,7 +9,7 @@ Agent Zero provides several basic operations through its interface:
9
### Restart Framework
10
The Restart button allows you to quickly restart the Agent Zero framework without using the terminal:
11
12
-
12
+
13
14
* Click the "Restart" button in the sidebar
15
* A blue notification will appear indicating "Restarting..."
@@ -24,7 +24,7 @@ The Restart button allows you to quickly restart the Agent Zero framework withou
24
### Action Buttons
25
Located beneath the chat input box, Agent Zero provides a set of action buttons for enhanced control and visibility:
26
27
-
27
+
28
#### Chat Flow Control
29
* **Pause/Resume Agent:** Toggle button to pause and resume chat flow
30
- Click to pause ongoing agent operations
@@ -36,7 +36,7 @@ Located beneath the chat input box, Agent Zero provides a set of action buttons
36
- Supports `.txt`, `.pdf`, `.csv`, `.html`, `.json`, and `.md` formats
37
- Files are stored in `/a0/knowledge/custom/main`
38
- Success message confirms successful import
39
- - See [knowledge](architecture.md#knowledge) for more details
39
+ - See [knowledge](../advanced/architecture.md#knowledge) for more details
40
41
### File Browser: Manage files in the Agent Zero environment
42
- Upload new files and folders
@@ -52,7 +52,7 @@ Located beneath the chat input box, Agent Zero provides a set of action buttons
52
- Shows current conversation context
53
- Displays active instructions and parameters
54
55
-
55
+
56
57
### History:
58
Access the chat history in JSON format
@@ -60,14 +60,14 @@ Access the chat history in JSON format
60
- Useful for debugging and understanding agent behavior
61
- Files are stored under `/a0/tmp/chats/` inside the container
62
63
-
63
+
64
65
* **Nudge:** Restart the agent's last process
66
- Useful when agents become unresponsive
67
- Retries the last operation
68
- Helps recover from stuck states
69
70
-
70
+
71
72
> [!TIP]
73
> Use the Context and History buttons to understand how the agent interprets your instructions and debug any unexpected behavior.
@@ -83,7 +83,7 @@ Agent Zero supports direct file attachments in the chat interface for seamless f
83
- Images show thumbnails when available
84
- Files are listed in the chat input area waiting to be sent
85
86
-
86
+
87
88
#### Working with Attached Files
89
* Files can be referenced directly in your messages
@@ -93,13 +93,13 @@ Agent Zero supports direct file attachments in the chat interface for seamless f
93
- Perform operations on multiple files simultaneously
94
- Confirm successful file operations with detailed responses
95
96
-
96
+
97
98
> [!TIP]
99
> 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.
100
101
## Tool Usage
102
-Agent Zero's power comes from its ability to use [tools](architecture.md#tools). Here's how to leverage them effectively:
102
+Agent Zero's power comes from its ability to use [tools](../advanced/architecture.md#tools). Here's how to leverage them effectively:
103
104
- **Understand Tools:** Agent Zero includes default tools like knowledge (powered by SearXNG), code execution, and communication. Understand the capabilities of these tools and how to invoke them.
105
@@ -110,7 +110,7 @@ The built-in browser agent currently has dependency issues on some systems. If w
110
- **Chrome DevTools MCP**
111
- **Playwright MCP**
112
113
-See [MCP Setup](mcp_setup.md) for configuration guidance and recommended servers.
113
+See [MCP Setup](../getting-started/mcp-setup.md) for configuration guidance and recommended servers.
114
115
## Example of Tools Usage: Web Search and Code Execution
116
Let's say you want Agent Zero to perform some financial analysis tasks. Here's a possible prompt:
@@ -134,10 +134,10 @@ One of Agent Zero's unique features is multi-agent cooperation.
134
135
* **Creating Sub-Agents:** Agents can create sub-agents to delegate sub-tasks. This helps manage complexity and distribute workload.
136
* **Communication:** Agents can communicate with each other, sharing information and coordinating actions. The system prompt and message history play a key role in guiding this communication.
137
-* **Hierarchy:** Agent Zero uses a [hierarchical structure](architecture.md#agent-hierarchy-and-communication), with superior agents delegating tasks to subordinates. This allows for structured problem-solving and efficient resource allocation.
137
+* **Hierarchy:** Agent Zero uses a [hierarchical structure](../advanced/architecture.md#agent-hierarchy-and-communication), with superior agents delegating tasks to subordinates. This allows for structured problem-solving and efficient resource allocation.
138
139
-
140
-
139
+
140
+
141
142
## Projects
143
Projects create isolated workspaces with their own context, instructions, memory, and secrets. This prevents context bleed between unrelated tasks or clients.
@@ -146,7 +146,7 @@ Projects create isolated workspaces with their own context, instructions, memory
146
- Project instructions are automatically injected from `.a0proj/instructions/`
147
- Project memory and knowledge are stored separately from global memory
148
149
-See [Projects in Extensibility](extensibility.md#projects) for structure details and file locations.
149
+See [Projects in Extensibility](../development/extensibility.md#projects) for structure details and file locations.
150
151
## Tasks & Scheduling
152
Tasks allow Agent Zero to spawn scheduled or on-demand work in separate contexts.
@@ -156,7 +156,7 @@ Tasks allow Agent Zero to spawn scheduled or on-demand work in separate contexts
156
- **Dedicated context:** each task runs in its own chat context, which pairs well with Projects.
157
158
> [!TIP]
159
-> Combine **Projects + Tasks + Notifications** for recurring, scoped workflows (e.g., daily inbox summaries). See [Notifications](notifications.md) for alerts.
159
+> Combine **Projects + Tasks + Notifications** for recurring, scoped workflows (e.g., daily inbox summaries). See [Notifications](../advanced/notifications.md) for alerts.
160
161
## Prompt Engineering
162
Effective prompt engineering is crucial for getting the most out of Agent Zero. Here are some tips and techniques:
@@ -190,7 +190,7 @@ Enable voice responses from agents:
190
* Click the "Stop Speech" button above the input area to immediately stop any ongoing speech
191
* You can also click the speech button when hovering over messages to speak individual messages or their parts
192
193
-
193
+
194
195
- 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.
196
@@ -225,7 +225,7 @@ Configure STT settings in the Settings page:
225
- Duration: Set how long silence should last before ending recording
226
- Timeout: Set maximum waiting time before closing the microphone
227
228
-
228
+
229
230
> [!IMPORTANT]
231
> All STT and TTS functionalities operate locally within the Docker container,
@@ -240,7 +240,7 @@ Configure STT settings in the Settings page:
240
- Integrals, summations, and limits
241
- Mathematical alignments and equations
242
243
-
243
+
244
245
> [!TIP]
246
> When asking the agent to solve mathematical problems, it will automatically respond using KaTeX formatting for clear and professional-looking mathematical expressions.
@@ -258,7 +258,7 @@ Agent Zero provides a powerful file browser interface for managing your workspac
258
- Download button
259
- Delete button (with confirmation)
260
261
-
261
+
262
263
#### Features
264
- **Directory Navigation**:
docs/res/setup/6-docker-a0-running-new.png
Binary files /dev/null and b/docs/res/setup/6-docker-a0-running-new.png differ
docs/res/setup/6-docker-a0-running.png
Binary files a/docs/res/setup/6-docker-a0-running.png and /dev/null differ
docs/tutorials/README.md
new
+20
@@ -0,0 +1,20 @@
1
+# Agent Zero Video Library
2
+
3
+Welcome to the visual guide for Agent Zero. Here you'll find tutorials, walkthroughs, and real-world use cases.
4
+
5
+## 📺 Basics
6
+- **[UI Walkthrough](basics.md)**: A tour of the interface, settings, and basic controls.
7
+- **[Installation Guide](https://www.youtube.com/watch?v=w5v5Kjx51hs)**: Getting started on your machine.
8
+
9
+## 💡 Use Case Showcases
10
+
11
+| Use Case | Description | Link |
12
+|----------|-------------|------|
13
+| **Data Analysis** | Financial trending, charting, and report generation | [View Guide](data-analysis.md) |
14
+| **Coding Assistant** | Building a full-stack web application from scratch | [View Guide](coding-assistant.md) |
15
+| **Deep Research** | Gathering papers, summarizing, and synthesizing info | [View Guide](research.md) |
16
+
17
+## 🎓 Advanced Tutorials
18
+- [MCP Server Setup](https://youtu.be/pM5f4Vz3_IQ)
19
+- [Projects & Workspaces](https://youtu.be/RrTDp_v9V1c)
20
+- [Memory Management](https://youtu.be/sizjAq2-d9s)
docs/tutorials/basics.md
new
+9
@@ -0,0 +1,9 @@
1
+# UI Walkthrough
2
+
3
+*(Placeholder for screenshots of the new Dashboard, Chat Interface, and Settings)*
4
+
5
+## The Dashboard
6
+
7
+
8
+## Chat Interface
9
+
docs/tutorials/coding-assistant.md
new
+5
@@ -0,0 +1,5 @@
1
+# Coding Assistant Use Case
2
+
3
+**Goal:** Build a React dashboard with real-time data visualization.
4
+
5
+*(Placeholder for step-by-step video/screenshots)*
docs/tutorials/data-analysis.md
new
+5
@@ -0,0 +1,5 @@
1
+# Financial Analysis Use Case
2
+
3
+**Goal:** Analyze Bitcoin/USD price trends and generate a highlighted chart.
4
+
5
+*(Placeholder for step-by-step video/screenshots)*
docs/tutorials/research.md
new
+5
@@ -0,0 +1,5 @@
1
+# Deep Research Use Case
2
+
3
+**Goal:** Gather and summarize recent AI papers about CoT prompting.
4
+
5
+*(Placeholder for step-by-step video/screenshots)*