plugin standards in docs; enhance A0 knowledge/main
docs: update installation guide thumbnail and URL - Updated the video URL and thumbnail to be the new script-based installation guide from YT in README.md and internal docs. --- - Standardize Python imports for user plugins to `usr.plugins.<plugin_name>...`, replacing sys.path hacks and symlink-dependent patterns - Add cleanup policy: plugins must not leave permanent system modifications (symlinks, orphaned services, stray files) after deletion - Remove superseded plugin-import-standards-report.md (recommendations are now integrated into the actual docs) - Updated surfaces: AGENTS.md, AGENTS.plugins.md, developer/plugins.md, a0-create-plugin skill --- update AGENTS.md and enhance agent-facing knowledge of A0 Enhanced the knowledge of the framework by removing the 1:1 copy of our GitHub README.md at the root and replacing it with a docs set for agents, to know more about Agent Zero without all the noise from URLs, explanations meant only for users. Updated AGENTS.md accordingly.
Alessandro committed
Mar 14, 2026 at 16:07 UTC
48632c2a959bd6720ad9964d325ac819d6e0a38c
14 files changed
+503
-979
AGENTS.md
+10
@@ -88,6 +88,13 @@ When running in Docker, Agent Zero uses two distinct Python runtimes to isolate
88
├── plugins/ # Core system plugins
89
├── agents/ # Agent profiles (prompts and config)
90
├── prompts/ # System and message prompt templates
91
+├── knowledge/
92
+│ └── main/about/ # Agent self-knowledge (indexed into vector DB for runtime recall)
93
+│ ├── identity.md # Philosophy, principles, project context
94
+│ ├── architecture.md # Agent loop, memory pipeline, multi-agent, extensions
95
+│ ├── capabilities.md # Detailed capabilities and limitations
96
+│ ├── configuration.md # LLM roles, providers, profiles, plugins, settings
97
+│ └── setup-and-deployment.md # Docker deployment, updates, troubleshooting
98
└── tests/ # Pytest suite
99
```
100
@@ -96,6 +103,7 @@ Key Files:
103
- python/helpers/plugins.py: Plugin discovery and configuration logic.
104
- webui/js/AlpineStore.js: Store factory for reactive frontend state.
105
- python/helpers/api.py: Base class for all API endpoints.
106
+- knowledge/main/about/: Agent self-knowledge files, indexed into the vector DB for runtime recall. Not user-facing docs - written for the agent's internal reference.
107
- docs/agents/AGENTS.components.md: Deep dive into the frontend component architecture.
108
- docs/agents/AGENTS.modals.md: Guide to the stacked modal system.
109
- docs/agents/AGENTS.plugins.md: Comprehensive guide to the full-stack plugin system.
@@ -128,11 +136,13 @@ Key Files:
136
- Location: Always develop new plugins in usr/plugins/.
137
- Manifest: Every plugin requires a plugin.yaml with name, description, version, and optionally settings_sections, per_project_config, per_agent_config, and always_enabled.
138
- Discovery: Conventions based on folder names (api/, tools/, webui/, extensions/).
139
+- Plugin-local Python imports: Prefer `usr.plugins.<plugin_name>...` for code that lives under `usr/plugins/`. Avoid `sys.path` hacks and avoid symlink-dependent `plugins.<plugin_name>...` imports for community plugins.
140
- Runtime hooks: Plugins may also expose hooks in hooks.py, callable by the framework through helpers.plugins.call_plugin_hook(...).
141
- Hook runtime: hooks.py executes inside the Agent Zero framework Python environment, so sys.executable -m pip installs dependencies into that same framework runtime.
142
- Environment targeting: If a plugin needs packages or binaries for the separate agent execution runtime or system environment, it must explicitly switch environments in a subprocess by targeting the correct interpreter, virtualenv, or package manager.
143
- Settings: Use get_plugin_config(plugin_name, agent=agent) to retrieve settings. Plugins can expose a UI for settings via webui/config.html. Plugin settings modals instantiate a local context from $store.pluginSettingsPrototype; bind plugin fields to config.* and use context.* for modal-level state and actions. For plugins wrapping core settings, set context.saveMode = 'core' in x-init.
144
- Activation: Global and scoped activation rules are stored as .toggle-1 (ON) and .toggle-0 (OFF). Scoped rules are handled via the plugin "Switch" modal.
145
+- Cleanup rule: Plugins should not permanently modify the system in ways that outlive the plugin. Deleting a plugin should not leave behind symlinks, unmanaged services, or stray files outside plugin-owned paths unless the user explicitly requested that behavior.
146
147
### Lifecycle Synchronization
148
| Action | Backend Extension | Frontend Lifecycle |
README.md
+1
-1
@@ -51,7 +51,7 @@ Or see DeepWiki generated documentation:
51
52
Click to open a video to learn how to install Agent Zero:
53
54
-[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
54
+[](https://www.youtube.com/watch?v=2-qFNUvqrXA)
55
56
A detailed setup guide for Windows, macOS, and Linux with a video can be found in the Agent Zero Documentation at [this page](./docs/setup/installation.md).
57
docs/agents/AGENTS.plugins.md
+32
@@ -44,6 +44,36 @@ usr/plugins/<plugin_name>/
44
└── ... # Full plugin pages/components
45
```
46
47
+### Python import rule for user plugins
48
+
49
+For plugin-local Python code in `usr/plugins/<plugin_name>/`, import through the
50
+fully qualified `usr.plugins.<plugin_name>...` package path.
51
+
52
+Good (DO):
53
+
54
+```python
55
+from usr.plugins.my_plugin.helpers.runtime import do_work
56
+import usr.plugins.my_plugin.helpers.state as state
57
+```
58
+
59
+Avoid (DON'T):
60
+
61
+```python
62
+# sys.path hacks
63
+sys.path.insert(0, ...)
64
+from helpers.runtime import do_work
65
+
66
+# persistent symlink-based imports
67
+from plugins.my_plugin.helpers.runtime import do_work
68
+```
69
+
70
+Why:
71
+
72
+- `usr.plugins...` works without renaming `helpers/`
73
+- it avoids `sys.path` mutation for plugin-local imports
74
+- it avoids installation-time symlinks into `/a0/plugins/`
75
+- it keeps plugin removal reversible, with no import wiring left behind
76
+
77
### plugin.yaml (runtime manifest)
78
79
This is the manifest file that lives inside your plugin directory and drives runtime behavior. It is distinct from the index manifest (`index.yaml`) used when publishing to the Plugin Index (see Section 7).
@@ -79,6 +109,7 @@ Design guidance:
109
- use `execute.py` for manual operations the user may need to run again later
110
- prefer making it rerunnable or state-aware
111
- avoid placing framework-internal automatic behavior here; that belongs in `hooks.py` or lifecycle extensions
112
+- do not make permanent system modifications that remain after plugin deletion unless the user explicitly asked for them and the plugin also provides a clear cleanup path
113
114
### hooks.py (framework runtime hooks)
115
@@ -88,6 +119,7 @@ Plugins can include an optional `hooks.py` file at the plugin root. Agent Zero l
119
- Use it for framework-internal operations such as install-time setup, plugin registration work, filesystem preparation, cache updates, or other tasks that need access to Agent Zero internals.
120
- Hook functions may be synchronous or async. Async hooks are awaited by the framework.
121
- Hook modules are cached until plugin caches are cleared, so changes may require a plugin refresh/reload cycle.
122
+- Plugin hooks should be cleanup-safe. A plugin should not leave behind permanent system modifications, symlinks, files outside its owned paths, or background services that survive plugin removal unless that behavior is explicitly part of the user-facing contract.
123
124
Current example: the plugin installer calls `install()` from `hooks.py` after a plugin is copied into place.
125
docs/developer/plugins.md
+31
@@ -70,6 +70,31 @@ usr/plugins/<plugin_name>/
70
└── ...
71
```
72
73
+## Python Imports for User Plugins
74
+
75
+For plugin-local Python imports inside `usr/plugins/<plugin_name>/`, use the
76
+fully qualified `usr.plugins.<plugin_name>...` path.
77
+
78
+Good:
79
+
80
+```python
81
+from usr.plugins.my_plugin.helpers.runtime import do_work
82
+import usr.plugins.my_plugin.helpers.state as state
83
+```
84
+
85
+Avoid:
86
+
87
+```python
88
+sys.path.insert(0, ...)
89
+from helpers.runtime import do_work
90
+
91
+from plugins.my_plugin.helpers.runtime import do_work
92
+```
93
+
94
+This is the preferred pattern because it keeps plugin imports explicit,
95
+requires no directory renaming like `name_helpers`, requires no symlink into
96
+`plugins/`, and leaves no global import hack behind when the plugin is deleted.
97
+
98
## Plugin Script (`execute.py`)
99
100
Plugins can include an optional `execute.py` at the plugin root for user-triggered operations such as setup, post-install actions, maintenance, repair steps, or other manual tasks that should run only when explicitly requested.
@@ -102,6 +127,11 @@ if __name__ == "__main__":
127
128
Return `0` on success, non-zero on failure. Print progress for user feedback. Use `sys.executable` for pip commands. Prefer making the script safe to run more than once; if reruns are not safe, detect the current state and print a clear explanation.
129
130
+First rule of plugin side effects: do not modify the system permanently unless
131
+the user explicitly asked for it and the plugin also provides a cleanup path.
132
+Deleting a plugin should not leave behind symlinks, orphaned services,
133
+framework patches, or unmanaged files outside plugin-owned locations.
134
+
135
## Runtime Hooks (`hooks.py`)
136
137
Plugins can also include an optional `hooks.py` at the plugin root. Agent Zero loads this module on demand and calls exported functions by name through `helpers.plugins.call_plugin_hook(...)`.
@@ -110,6 +140,7 @@ Plugins can also include an optional `hooks.py` at the plugin root. Agent Zero l
140
- Use it for framework-internal operations such as install hooks, registration, cache preparation, file setup, or other work that needs direct access to framework internals.
141
- Hook functions may be synchronous or async.
142
- Hook modules are cached, so edits may require a plugin refresh or cache clear before changes are picked up.
143
+- Hooks should be reversible and cleanup-safe. Prefer plugin-owned paths and framework-managed state over permanent system modifications.
144
145
Use `execute.py` when the user should explicitly decide when the operation runs. Use `hooks.py` or lifecycle extensions when the work belongs to framework-managed behavior.
146
docs/res/install_guide.png
Binary files /dev/null and b/docs/res/install_guide.png differ
docs/setup/installation.md
+1
-1
@@ -2,7 +2,7 @@
2
3
Click to open a video to learn how to install Agent Zero:
4
5
-[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
5
+[](https://www.youtube.com/watch?v=2-qFNUvqrXA)
6
7
## **Goal:** Go from zero to a first working chat with minimal setup.
8
knowledge/main/about/architecture.md
new
+67
@@ -0,0 +1,67 @@
1
+# Agent Zero - Internal Architecture
2
+
3
+## The Agent Loop (Monologue Cycle)
4
+
5
+Each agent runs a continuous monologue loop. On each cycle the agent receives its current context (system prompt + message history), produces a JSON response (thoughts, headline, tool name, tool args), and the framework executes the named tool. The tool result is appended to history and the loop continues until the agent calls `response` to deliver a final answer to its superior.
6
+
7
+The loop handles: message history management, context window limits (via summarization), memory recall injection, intervention from superiors, and error recovery (misformat retries, tool-not-found handling).
8
+
9
+## Context and State
10
+
11
+`AgentContext` (defined in `agent.py`) is the central state container for a conversation. It holds:
12
+- Agent number and identifier
13
+- Message history
14
+- The active agent profile and prompt configuration
15
+- Reference to memory, knowledge, and tool systems
16
+- Project context if a project is active
17
+- `extras` dict - additional content injected into the system prompt each turn (memories, solutions, agent info, workdir structure)
18
+
19
+Each WebSocket session connects to one `AgentContext`. Multiple concurrent chats run in separate contexts. The framework is initialized in `initialize.py` and the server entry point is `run_ui.py`.
20
+
21
+## Prompt Assembly
22
+
23
+System prompts are assembled from fragment files on each loop iteration. The main system prompt is `prompts/agent.system.main.md`, which includes sub-prompts via `{{ include "filename.md" }}` directives. Agent profiles (in `agents/<profile>/prompts/`) can override individual fragments. This means a subordinate with the `developer` profile gets a different role and communication section while sharing the same tool list and solving workflow as the base agent.
24
+
25
+Prompt fragments are in `prompts/`. Plugin system prompts are in `plugins/<plugin>/prompts/`. The assembled system prompt is dynamic - it changes based on profile, active project, loaded tools, recalled memories, and injected extras.
26
+
27
+## Multi-Agent Hierarchy
28
+
29
+The hierarchy is a tree with the human user at the root. Each node is an agent instance running in its own context. A superior calls `call_subordinate` with a message and optional profile name; this creates a new `AgentContext` and runs the subordinate agent's loop until it returns a response.
30
+
31
+Agent 0 is always the top-level agent whose superior is the user. When Agent 0 delegates a task to a subordinate, that subordinate can itself delegate further. There is no enforced depth limit. Agents share the same tool system but each has its own isolated context and history.
32
+
33
+Subordinates can be given specific prompt profiles (`developer`, `researcher`, or any custom profile in `agents/`). Profiles change the role, communication style, and available instructions without changing the underlying framework.
34
+
35
+## Memory and Knowledge Pipeline
36
+
37
+### Knowledge (vector DB, read-only)
38
+Knowledge files (in `knowledge/` and `usr/knowledge/`) are loaded at startup, embedded, and stored in a FAISS vector index per memory subdir. Files are tracked by checksum; only changed files are re-indexed. Supported formats: `.md`, `.txt`, `.pdf`, `.csv`, `.html`, `.json`.
39
+
40
+The memory areas are:
41
+- `main` - general knowledge and facts (files in knowledge root or `main/` subdir)
42
+- `fragments` - partial or supplementary knowledge
43
+- `solutions` - known solutions to problems
44
+
45
+### Recall (automatic, per conversation turn)
46
+The `RecallMemories` extension runs every N loop iterations (configurable). It queries the vector store using either the raw conversation or a utility-LLM-generated search query. Results from `main` and `fragments` areas plus `solutions` are injected into `loop_data.extras_persistent`, which gets rendered into the system prompt via `agent.context.extras.md` template.
47
+
48
+The agent sees recalled memories as a section in its system prompt labeled "Memories on the topic". The agent is instructed not to over-rely on them.
49
+
50
+### Agent memory (read-write, via memorize tool)
51
+The agent can explicitly save facts, solutions, and code snippets using the `memorize` tool. These are stored in the same FAISS index under the `main` or `solutions` area and recalled in future conversations. Memory can also be consolidated (summarized) and managed through the Memory Dashboard in the web UI.
52
+
53
+## Tool System
54
+
55
+Tools are Python classes in `python/tools/` that inherit from `Tool`. Each tool implements an `execute()` async method. Tools are discovered at startup and registered in the agent's tool list (rendered into the system prompt as `{{tools}}`). The agent names a tool in its JSON response; the framework finds and calls it.
56
+
57
+Plugin tools can be added in `plugins/<plugin>/tools/` or `usr/plugins/<plugin>/tools/` without modifying core files.
58
+
59
+## Extension and Plugin System
60
+
61
+The plugin system (`python/helpers/plugins.py`) discovers plugins from `plugins/` and `usr/plugins/`. Each plugin has a `plugin.yaml` manifest declaring name, version, and settings. Plugins can contribute: API handlers, tools, WebUI components, extensions, and hooks. User plugins in `usr/plugins/` are never overwritten by framework updates. The agent has skills to create, manage, debug, review and contribute plugins to the Plugin Index repository (https://github.com/agent0ai/a0-plugins)
62
+
63
+## Frontend Architecture
64
+
65
+The web UI is built with Alpine.js and ES module components. The main shell is `webui/index.html`. Components are in `webui/components/`. Frontend state is managed via Alpine stores defined with `createStore` from `/js/AlpineStore.js`.
66
+
67
+Real-time communication uses Socket.io WebSockets. The backend WebSocket handlers are in `python/websocket_handlers/`. API handlers are in `python/api/`, each deriving from `ApiHandler` in `python/helpers/api.py`.
knowledge/main/about/capabilities.md
new
+82
@@ -0,0 +1,82 @@
1
+# Agent Zero - Capabilities Reference
2
+
3
+## Code Execution
4
+
5
+The agent can write and execute code in any language available in the Docker container. The execution environment is a Kali Linux container with two Python runtimes:
6
+- `/opt/venv-a0` (Python 3.12) - the Agent Zero framework runtime
7
+- `/opt/venv` (Python 3.13) - the agent's execution runtime (default for agent-run code)
8
+
9
+The agent installs packages into the execution runtime (`/opt/venv`) via `pip install`. Packages needed by the framework itself must target `/opt/venv-a0`.
10
+
11
+Supported runtimes for code execution: Python, Node.js, Bash/shell. Other languages (Go, Rust, PHP, etc.) can be used if the compiler/runtime is installed in the container.
12
+
13
+Code runs in the terminal with real-time output streaming. Long-running processes, background jobs, and interactive sessions are supported. The agent can pause and resume code execution and interact with running processes.
14
+
15
+## Terminal and System Operations
16
+
17
+The agent has full root access to the Kali Linux Docker container. It can:
18
+- Install packages via `apt`, `pip`, `npm`, and other package managers
19
+- Create, read, write, move, and delete files anywhere in the container
20
+- Run any system command, manage processes, set up services
21
+- Access the network (HTTP requests, SSH, port scanning, etc.)
22
+- Use Kali Linux security tools pre-installed in the container
23
+
24
+## Skills (SKILL.md Standard)
25
+
26
+Skills are structured markdown files that provide contextual expertise for specific tasks. When a skill is relevant to the current task, it is loaded into the agent's context and followed as a set of instructions. Skills are discovered from:
27
+- `usr/skills/` (user-added skills)
28
+- Project-scoped skills in `.a0proj/skills/`
29
+- Skills imported via the web UI
30
+
31
+Skills follow the open SKILL.md standard, making them portable across tools that support it. The agent executes skill instructions using `code_execution_tool` or `skills_tool`.
32
+
33
+## Projects
34
+
35
+Projects provide isolated workspaces with their own:
36
+- Working directory (`usr/projects/<name>/`)
37
+- Memory and knowledge scope
38
+- Custom agent instructions (`.a0proj/agent.instructions.md`)
39
+- Secrets and credentials (stored encrypted, not visible in agent context)
40
+- MCP server configurations
41
+- Git repository (can be cloned directly with authentication)
42
+
43
+When a project is active, the agent's file operations, memory, and knowledge are scoped to that project. Projects prevent context bleed between separate work streams.
44
+
45
+## Knowledge Base Access
46
+
47
+The agent has automatic access to its knowledge base via similarity search. Knowledge is indexed from `knowledge/` (framework-level) and `usr/knowledge/<subdir>/` (user-level). The agent does not need to explicitly query knowledge - relevant content is surfaced automatically with memory recall. The `knowledge_tool` can also be called explicitly for targeted lookups.
48
+
49
+## Multi-Agent Delegation
50
+
51
+The agent can spawn subordinate agents with the `call_subordinate` tool. Subordinates can be given:
52
+- Specific prompt profiles (`developer`, `researcher`, custom profiles)
53
+- A defined role and task scope
54
+- Access to the same tool set
55
+
56
+Delegation is used to: parallelize work, maintain clean context per task, apply specialized profiles, and isolate long subtasks from the main context.
57
+
58
+## Document Query
59
+
60
+The `document_query_tool` can load and query arbitrary documents (local files or URLs) using a separate RAG pipeline. Unlike the knowledge base (which is pre-indexed), this tool indexes documents on demand with a configurable chunk size. Useful for analyzing large documents, codebases, or external content without polluting the persistent knowledge store.
61
+
62
+## Scheduler
63
+
64
+The agent can schedule tasks to run at specified times or intervals using the scheduler tool. Scheduled tasks run in the background with their own agent instances. Tasks are managed via the Scheduler UI in the web interface.
65
+
66
+## External API and MCP
67
+
68
+Agent Zero can act as both an MCP server and an MCP client:
69
+- As an **MCP server**: exposes agent capabilities to other MCP-compatible clients
70
+- As an **MCP client**: uses tools from external MCP servers (configured per project or globally)
71
+
72
+An external REST API is available for programmatic task submission. Agent-to-Agent (A2A) protocol is supported for inter-system agent communication.
73
+
74
+## Limitations
75
+
76
+- **No persistent state between chats** unless explicitly memorized or saved to files.
77
+- **Context window**: long conversations are summarized automatically, which can lose detail.
78
+- **Memory recall is approximate**: similarity search may miss relevant memories or surface irrelevant ones.
79
+- **No GUI interaction** outside the browser agent (which is separate from the main agent).
80
+- **Container boundary**: the agent cannot affect systems outside the Docker container unless network access or volume mounts are configured.
81
+- **Model capability ceiling**: tool usage quality and reasoning depth are bounded by the underlying LLM. Small models may struggle with complex multi-step tool use.
82
+- **No real-time data** beyond web search. The agent's own knowledge cutoff is the underlying model's training cutoff.
knowledge/main/about/configuration.md
new
+102
@@ -0,0 +1,102 @@
1
+# Agent Zero - Configuration Reference
2
+
3
+## LLM Roles
4
+
5
+Agent Zero uses four distinct LLM roles, each configurable independently:
6
+
7
+| Role | Purpose |
8
+|------|---------|
9
+| `chat_llm` | Primary model for all agent reasoning and tool use |
10
+| `utility_llm` | Secondary model for internal framework tasks: memory summarization, query generation, history compression, memory recall filtering |
11
+| `browser_llm` | Model used by the browser agent; vision capability recommended |
12
+| `embedding_llm` | Produces vector embeddings for memory and knowledge indexing |
13
+
14
+The utility model handles high-volume, lower-stakes operations and can be a cheaper/faster model than the chat model. Changing the embedding model invalidates the existing vector index - the entire knowledge base is re-indexed automatically.
15
+
16
+## Model Providers
17
+
18
+Providers are defined in `conf/model_providers.yaml`. All chat and embedding providers go through LiteLLM, which normalizes the API interface. Supported chat providers (as of v0.9.8):
19
+
20
+- Agent Zero API (a0_venice) - hosted service with no API key required for basic use
21
+- Anthropic, OpenAI, OpenRouter, Google (Gemini), Groq, Mistral AI
22
+- DeepSeek, xAI, Moonshot AI, Sambanova, CometAPI, Z.AI, Inception AI
23
+- Venice.ai, AWS Bedrock, Azure OpenAI
24
+- GitHub Copilot, HuggingFace
25
+- Ollama, LM Studio (local models)
26
+- Other OpenAI-compatible endpoints (custom `api_base`)
27
+
28
+Embedding providers: OpenAI, Azure, Ollama, LM Studio, HuggingFace, Google, Mistral, OpenRouter (via OpenAI-compat), AWS Bedrock.
29
+
30
+### Model Naming Convention
31
+
32
+| Provider | Format |
33
+|----------|--------|
34
+| OpenAI | model name only (`gpt-4.1`, `o4-mini`) |
35
+| Anthropic | model name only (`claude-sonnet-4-5`) |
36
+| OpenRouter | `provider/model` (`anthropic/claude-sonnet-4-5`) |
37
+| Ollama | model name only (`llama3.2`, `qwen2.5`) |
38
+| Google | model name only (`gemini-2.0-flash`) |
39
+
40
+## Agent Profiles
41
+
42
+Profiles are in `agents/<profile>/`. Each profile can override any prompt fragment from the base `prompts/` directory. Built-in profiles:
43
+
44
+| Profile | Description |
45
+|---------|-------------|
46
+| `default` | Base template for creating new profiles |
47
+| `agent0` | Top-level general assistant; human as superior; delegates to specialized subordinates |
48
+| `developer` | "Master Developer" - software architecture and full-stack implementation focus |
49
+| `researcher` | "Deep Research" - research, analysis, and synthesis across academic and corporate domains |
50
+| `hacker` | Red/blue team; penetration testing; Kali tools focus |
51
+| `_example` | Minimal example for building custom profiles |
52
+
53
+Custom profiles go in `usr/agents/<profile>/` to survive framework updates.
54
+
55
+## Plugin System
56
+
57
+Plugins are discovered from `plugins/` (framework plugins) and `usr/plugins/` (user plugins). Each plugin requires a `plugin.yaml` with at minimum: `name`, `description`, `version`.
58
+
59
+### Activation
60
+
61
+- **Global activation**: enabled/disabled for all contexts via the Plugins settings panel
62
+- **Scoped activation**: enabled/disabled per project or per agent profile via the plugin Switch modal
63
+- Activation state stored as `.toggle-1` (ON) and `.toggle-0` (OFF) files in the plugin's config dir
64
+
65
+### Built-in Framework Plugins
66
+
67
+| Plugin | Purpose |
68
+|--------|---------|
69
+| `_memory` | Memory and knowledge pipeline, recall, consolidation |
70
+| `_code_execution` | Terminal and code execution tool |
71
+| `_text_editor` | Structured file read/write/patch tool |
72
+
73
+## Environment Variable Configuration
74
+
75
+Any setting can be set via environment variable using the `A0_SET_` prefix. This is the primary mechanism for automated deployment and container configuration.
76
+
77
+Format: `A0_SET_<setting_name>=<value>`
78
+
79
+Examples:
80
+```
81
+A0_SET_chat_model_provider=anthropic
82
+A0_SET_chat_model_name=claude-sonnet-4-5
83
+A0_SET_utility_model_provider=openai
84
+A0_SET_utility_model_name=gpt-4o-mini
85
+A0_SET_embedding_model_provider=openai
86
+A0_SET_embedding_model_name=text-embedding-3-small
87
+```
88
+
89
+These can be set in the `.env` file at the project root or passed as Docker `-e` flags during container creation.
90
+
91
+## Key Behavioral Settings
92
+
93
+| Setting | Effect |
94
+|---------|--------|
95
+| `agent_knowledge_subdir` | Which knowledge subdir to load (default: `custom`, resolved to `usr/knowledge/`) |
96
+| `memory_recall_interval` | How many loop iterations between automatic memory recalls |
97
+| `memory_results` | Number of memory chunks returned per recall query |
98
+| `memory_threshold` | Similarity threshold for memory recall (0-1); lower = more results, potentially less relevant |
99
+| `auth_login` / `auth_password` | Web UI authentication credentials |
100
+| `agent_temperature` | LLM temperature for the chat model |
101
+
102
+Settings are stored in `usr/settings.json` and managed through the Settings page in the web UI. The settings page also provides: API key management (multiple keys per provider with round-robin), backup/restore, external services (tunnels, MCP, A2A), and memory management.
knowledge/main/about/github_readme.md
deleted
-392
@@ -1,392 +0,0 @@
1
-<div align="center">
2
-
3
-# `Agent Zero`
4
-
5
-<p align="center">
6
- <a href="https://trendshift.io/repositories/11745" target="_blank"><img src="https://trendshift.io/api/badge/repositories/11745" alt="frdel%2Fagent-zero | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
7
-</p>
8
-
9
-[](https://agent-zero.ai) [](https://github.com/sponsors/agent0ai) [](https://x.com/Agent0ai) [](https://discord.gg/B8KZKNsPpj) [](https://www.youtube.com/@AgentZeroFW) [](https://www.linkedin.com/in/jan-tomasek/) [](https://warpcast.com/agent-zero)
10
-
11
-
12
-## Documentation:
13
-
14
-[Introduction](#a-personal-organic-agentic-framework-that-grows-and-learns-with-you) •
15
-[Installation](./docs/setup/installation.md) •
16
-[How to update](./docs/setup/installation.md#how-to-update-agent-zero) <br>
17
-[Development Setup](./docs/setup/dev-setup.md) •
18
-[Usage](./docs/guides/usage.md)
19
-
20
-Or see DeepWiki generated documentation:
21
-
22
-[](https://deepwiki.com/agent0ai/agent-zero)
23
-
24
-</div>
25
-
26
-
27
-<div align="center">
28
-
29
-> ### 🚨 **AGENT ZERO SKILLS** 🚨
30
-> **Skills System** - portable, structured agent capabilities using the open `SKILL.md` standard (compatible with Claude Code, Codex and more).
31
->
32
-> **Plus:** Git-based Projects with authentication for public/private repositories - clone codebases directly into isolated workspaces.
33
->
34
-> See [Usage Guide](./docs/guides/usage.md) and [Projects Tutorial](./docs/guides/projects.md) to get started.
35
-</div>
36
-
37
-
38
-
39
-[](https://youtu.be/lazLNcEYsiQ)
40
-
41
-
42
-## A personal, organic agentic framework that grows and learns with you
43
-
44
-
45
-
46
-- Agent Zero is not a predefined agentic framework. It is designed to be dynamic, organically growing, and learning as you use it.
47
-- Agent Zero is fully transparent, readable, comprehensible, customizable, and interactive.
48
-- Agent Zero uses the computer as a tool to accomplish its (your) tasks.
49
-
50
-# ⚙️ Installation
51
-
52
-Click to open a video to learn how to install Agent Zero:
53
-
54
-[](https://www.youtube.com/watch?v=w5v5Kjx51hs)
55
-
56
-A detailed setup guide for Windows, macOS, and Linux with a video can be found in the Agent Zero Documentation at [this page](./docs/setup/installation.md).
57
-
58
-### ⚡ Quick Start
59
-
60
-```bash
61
-# Pull and run with Docker
62
-
63
-docker pull agent0ai/agent-zero
64
-docker run -p 50001:80 agent0ai/agent-zero
65
-
66
-# Visit http://localhost:50001 to start
67
-```
68
-
69
-
70
-# 💡 Key Features
71
-
72
-1. **General-purpose Assistant**
73
-
74
-- Agent Zero is not pre-programmed for specific tasks (but can be). It is meant to be a general-purpose personal assistant. Give it a task, and it will gather information, execute commands and code, cooperate with other agent instances, and do its best to accomplish it.
75
-- It has a persistent memory, allowing it to memorize previous solutions, code, facts, instructions, etc., to solve tasks faster and more reliably in the future.
76
-
77
-
78
-
79
-2. **Computer as a Tool**
80
-
81
-- Agent Zero uses the operating system as a tool to accomplish its tasks. It has no single-purpose tools pre-programmed. Instead, it can write its own code and use the terminal to create and use its own tools as needed.
82
-- The only default tools in its arsenal are online search, memory features, communication (with the user and other agents), and code/terminal execution. Everything else is created by the agent itself or can be extended by the user.
83
-- Tool usage functionality has been developed from scratch to be the most compatible and reliable, even with very small models.
84
-- **Default Tools:** Agent Zero includes tools like knowledge, code execution, and communication.
85
-- **Creating Custom Tools:** Extend Agent Zero's functionality by creating your own custom tools.
86
-- **Skills (SKILL.md Standard):** Skills are contextual expertise loaded dynamically when relevant. They use the open SKILL.md standard (developed by Anthropic), making them compatible with Claude Code, Cursor, Goose, OpenAI Codex CLI, and GitHub Copilot.
87
-
88
-3. **Multi-agent Cooperation**
89
-
90
-- Every agent has a superior agent giving it tasks and instructions. Every agent then reports back to its superior.
91
-- In the case of the first agent in the chain (Agent 0), the superior is the human user; the agent sees no difference.
92
-- Every agent can create its subordinate agent to help break down and solve subtasks. This helps all agents keep their context clean and focused.
93
-
94
-
95
-
96
-4. **Completely Customizable and Extensible**
97
-
98
-- Almost nothing in this framework is hard-coded. Nothing is hidden. Everything can be extended or changed by the user.
99
-- The whole behavior is defined by a system prompt in the **prompts/default/agent.system.md** file. Change this prompt and change the framework dramatically.
100
-- The framework does not guide or limit the agent in any way. There are no hard-coded rails that agents have to follow.
101
-- Every prompt, every small message template sent to the agent in its communication loop can be found in the **prompts/** folder and changed.
102
-- Every default tool can be found in the **python/tools/** folder and changed or copied to create new predefined tools.
103
-- **Automated configuration** via `A0_SET_` environment variables for deployment automation and easy setup.
104
-
105
-
106
-
107
-5. **Communication is Key**
108
-
109
-- Give your agent a proper system prompt and instructions, and it can do miracles.
110
-- Agents can communicate with their superiors and subordinates, asking questions, giving instructions, and providing guidance. Instruct your agents in the system prompt on how to communicate effectively.
111
-- The terminal interface is real-time streamed and interactive. You can stop and intervene at any point. If you see your agent heading in the wrong direction, just stop and tell it right away.
112
-- There is a lot of freedom in this framework. You can instruct your agents to regularly report back to superiors asking for permission to continue. You can instruct them to use point-scoring systems when deciding when to delegate subtasks. Superiors can double-check subordinates' results and dispute. The possibilities are endless.
113
-
114
-## 🚀 Real-world use cases
115
-
116
-- **Financial Analysis & Charting** - `"Find last month's Bitcoin/USD price trend, correlate with major cryptocurrency news events, generate annotated chart with highlighted key dates"`
117
-
118
-- **Excel Automation Pipeline** - `"Scan incoming directory for financial spreadsheets, validate and clean data, consolidate from multiple sources, generate executive reports with flagged anomalies"`
119
-
120
-- **API Integration Without Code** - `"Use this Google Gemini API snippet to generate product images, remember the integration for future use"` - agent learns and stores the solution in memory
121
-
122
-- **Automated Server Monitoring** - `"Check server status every 30 minutes: CPU usage, disk space, memory. Alert if metrics exceed thresholds"` (scheduled task with project-scoped credentials)
123
-
124
-- **Multi-Client Project Isolation** - Separate projects for each client with isolated memory, custom instructions, and dedicated secrets - prevents context bleed across sensitive work
125
-
126
-## 🐳 Fully Dockerized, with Speech-to-Text and TTS
127
-
128
-
129
-
130
-- Customizable settings allow users to tailor the agent's behavior and responses to their needs.
131
-- The Web UI output is very clean, fluid, colorful, readable, and interactive; nothing is hidden.
132
-- You can load or save chats directly within the Web UI.
133
-- The same output you see in the terminal is automatically saved to an HTML file in **logs/** folder for every session.
134
-
135
-
136
-
137
-- Agent output is streamed in real-time, allowing users to read along and intervene at any time.
138
-- No coding is required; only prompting and communication skills are necessary.
139
-- With a solid system prompt, the framework is reliable even with small models, including precise tool usage.
140
-
141
-## 👀 Keep in Mind
142
-
143
-1. **Agent Zero Can Be Dangerous!**
144
-
145
-- With proper instruction, Agent Zero is capable of many things, even potentially dangerous actions concerning your computer, data, or accounts. Always run Agent Zero in an isolated environment (like Docker) and be careful what you wish for.
146
-
147
-2. **Agent Zero Is Prompt-based.**
148
-
149
-- The whole framework is guided by the **prompts/** folder. Agent guidelines, tool instructions, messages, utility AI functions, it's all there.
150
-
151
-
152
-## 📚 Read the Documentation
153
-
154
-| Page | Description |
155
-|-------|-------------|
156
-| [Installation](./docs/setup/installation.md) | Installation, setup and configuration |
157
-| [Usage](./docs/guides/usage.md) | Basic and advanced usage |
158
-| [Guides](./docs/guides/) | Step-by-step guides: Usage, Projects, API Integration, MCP Setup, A2A Setup |
159
-| [Development Setup](./docs/setup/dev-setup.md) | Development and customization |
160
-| [WebSocket Infrastructure](./docs/developer/websockets.md) | Real-time WebSocket handlers, client APIs, filtering semantics, envelopes |
161
-| [Extensions](./docs/developer/extensions.md) | Extending Agent Zero |
162
-| [Connectivity](./docs/developer/connectivity.md) | External API endpoints, MCP server connections, A2A protocol |
163
-| [Architecture](./docs/developer/architecture.md) | System design and components |
164
-| [Contributing](./docs/guides/contribution.md) | How to contribute |
165
-| [Troubleshooting](./docs/guides/troubleshooting.md) | Common issues and their solutions |
166
-
167
-
168
-## 🎯 Changelog
169
-
170
-### v0.9.8 - Skills, UI Redesign & Git projects
171
-[Release video](https://youtu.be/NV7s78yn6DY)
172
-
173
-- Skills
174
- - Skills System replacing the legacy Instruments with a new `SKILL.md` standard for structured, portable agent capabilities.
175
- - Built-in skills, and UI support for importing and listing skills
176
-- Real-time WebSocket infrastructure replacing the polling-based approach for UI state synchronization
177
-- UI Redesign
178
- - Process groups to visually group agent actions with expand/collapse support
179
- - Timestamps, steps count and execution time with tool-specific badges
180
- - Step detail modals with key-value and raw JSON display
181
- - Collapsible responses with show more/less and copy buttons on code blocks and tables
182
- - Message queue system allowing users to queue messages while the agent is still processing
183
- - In-browser file editor for viewing and editing files without leaving the UI
184
- - Welcome screen redesign with info and warning banners for connection security, missing API keys, and system resources
185
- - Scheduler redesign with standalone modal, separate task list, detail and editor components, and project support
186
- - Smooth response rendering and scroll stabilization across chat, terminals, and image viewer
187
- - Chat width setting and reworked preferences panel
188
- - Image viewer improvements with scroll support and expanded viewer
189
- - Redesigned sidebar with reusable dropdown component and streamlined buttons
190
- - Inline button confirmations for critical actions
191
- - Improved login design and new logout button
192
- - File browser enhanced with rename and file actions dropdown
193
-- Git projects
194
- - Git-based projects with clone authentication for public and private repositories
195
-- Four new LLM providers: CometAPI, Z.AI, Moonshot AI, and AWS Bedrock
196
-- Microsoft Dev Tunnels integration for secure remote access
197
-- User data migration to `/usr` directory for cleaner separation of user and system files
198
-- Subagents system with configurable agent profiles for different roles
199
-- Memory operations offloaded to deferred tasks for better performance
200
-- Environment variables can now configure settings via `A0_SET_*` prefix in `.env`
201
-- Automatic migration with overwrite support for `.env`, scheduler, knowledge, and legacy directories
202
-- Projects support extended to MCP, A2A, and external API
203
-- Workdir outside project support for more flexible file organization
204
-- Agent number tracking in backend and responses for multi-agent identification
205
-- Many bug fixes and stability improvements across the UI, MCP tools, scheduler, uploads, and WebSocket handling
206
-
207
-
208
-### v0.9.7 - Projects
209
-[Release video](https://youtu.be/RrTDp_v9V1c)
210
-- Projects management
211
- - Support for custom instructions
212
- - Integration with memory, knowledge, files
213
- - Project specific secrets
214
-- New Welcome screen/Dashboard
215
-- New Wait tool
216
-- Subordinate agent configuration override support
217
-- Support for multiple documents at once in document_query_tool
218
-- Improved context on interventions
219
-- Openrouter embedding support
220
-- Frontend components refactor and polishing
221
-- SSH metadata output fix
222
-- Support for windows powershell in local TTY utility
223
-- More efficient selective streaming for LLMs
224
-- UI output length limit improvements
225
-
226
-### v0.9.6 - Memory Dashboard
227
-[Release video](https://youtu.be/sizjAq2-d9s)
228
-- Memory Management Dashboard
229
-- Kali update
230
-- Python update + dual installation
231
-- Browser Use update
232
-- New login screen
233
-- LiteLLM retry on temporary errors
234
-- Github Copilot provider support
235
-
236
-### v0.9.5 - Secrets
237
-[Release video](https://www.youtube.com/watch?v=VqxUdt7pjd8)
238
-- Secrets management - agent can use credentials without seeing them
239
-- Agent can copy paste messages and files without rewriting them
240
-- LiteLLM global configuration field
241
-- Custom HTTP headers field for browser agent
242
-- Progressive web app support
243
-- Extra model params support for JSON
244
-- Short IDs for files and memories to prevent LLM errors
245
-- Tunnel component frontend rework
246
-- Fix for timezone change bug
247
-- Notifications z-index fix
248
-
249
-### v0.9.4 - Connectivity, UI
250
-[Release video](https://www.youtube.com/watch?v=C2BAdDOduIc)
251
-- External API endpoints
252
-- Streamable HTTP MCP A0 server
253
-- A2A (Agent to Agent) protocol - server+client
254
-- New notifications system
255
-- New local terminal interface for stability
256
-- Rate limiter integration to models
257
-- Delayed memory recall
258
-- Smarter autoscrolling in UI
259
-- Action buttons in messages
260
-- Multiple API keys support
261
-- Download streaming
262
-- Tunnel URL QR code
263
-- Internal fixes and optimizations
264
-
265
-### v0.9.3 - Subordinates, memory, providers Latest
266
-[Release video](https://www.youtube.com/watch?v=-LfejFWL34k)
267
-- Faster startup/restart
268
-- Subordinate agents can have dedicated prompts, tools and system extensions
269
-- Streamable HTTP MCP server support
270
-- Memory loading enhanced by AI filter
271
-- Memory AI consolidation when saving memories
272
-- Auto memory system configuration in settings
273
-- LLM providers available are set by providers.yaml configuration file
274
-- Venice.ai LLM provider supported
275
-- Initial agent message for user + as example for LLM
276
-- Docker build support for local images
277
-- File browser fix
278
-
279
-### v0.9.2 - Kokoro TTS, Attachments
280
-[Release video](https://www.youtube.com/watch?v=sPot_CAX62I)
281
-
282
-- Kokoro text-to-speech integration
283
-- New message attachments system
284
-- Minor updates: log truncation, hyperlink targets, component examples, api cleanup
285
-
286
-### v0.9.1 - LiteLLM, UI improvements
287
-[Release video](https://youtu.be/crwr0M4Spcg)
288
-- Langchain replaced with LiteLLM
289
- - Support for reasoning models streaming
290
- - Support for more providers
291
- - Openrouter set as default instead of OpenAI
292
-- UI improvements
293
- - New message grouping system
294
- - Communication smoother and more efficient
295
- - Collapsible messages by type
296
- - Code execution tool output improved
297
- - Tables and code blocks scrollable
298
- - More space efficient on mobile
299
-- Streamable HTTP MCP servers support
300
-- LLM API URL added to models config for Azure, local and custom providers
301
-
302
-### v0.9.0 - Agent roles, backup/restore
303
-[Release video](https://www.youtube.com/watch?v=rMIe-TC6H-k)
304
-- subordinate agents can use prompt profiles for different roles
305
-- backup/restore functionality for easier upgrades
306
-- security and bug fixes
307
-
308
-### v0.8.7 - Formatting, Document RAG Latest
309
-[Release video](https://youtu.be/OQJkfofYbus)
310
-- markdown rendering in responses
311
-- live response rendering
312
-- document Q&A tool
313
-
314
-### v0.8.6 - Merge and update
315
-[Release video](https://youtu.be/l0qpK3Wt65A)
316
-- Merge with Hacking Edition
317
-- browser-use upgrade and integration re-work
318
-- tunnel provider switch
319
-
320
-### v0.8.5 - **MCP Server + Client**
321
-[Release video](https://youtu.be/pM5f4Vz3_IQ)
322
-
323
-- Agent Zero can now act as MCP Server
324
-- Agent Zero can use external MCP servers as tools
325
-
326
-### v0.8.4.1 - 2
327
-Default models set to gpt-4.1
328
-- Code execution tool improvements
329
-- Browser agent improvements
330
-- Memory improvements
331
-- Various bugfixes related to context management
332
-- Message formatting improvements
333
-- Scheduler improvements
334
-- New model provider
335
-- Input tool fix
336
-- Compatibility and stability improvements
337
-
338
-### v0.8.4
339
-[Release video](https://youtu.be/QBh_h_D_E24)
340
-
341
-- **Remote access (mobile)**
342
-
343
-### v0.8.3.1
344
-[Release video](https://youtu.be/AGNpQ3_GxFQ)
345
-
346
-- **Automatic embedding**
347
-
348
-### v0.8.3
349
-[Release video](https://youtu.be/bPIZo0poalY)
350
-
351
-- ***Planning and scheduling***
352
-
353
-### v0.8.2
354
-[Release video](https://youtu.be/xMUNynQ9x6Y)
355
-
356
-- **Multitasking in terminal**
357
-- **Chat names**
358
-
359
-### v0.8.1
360
-[Release video](https://youtu.be/quv145buW74)
361
-
362
-- **Browser Agent**
363
-- **UX Improvements**
364
-
365
-### v0.8
366
-[Release video](https://youtu.be/cHDCCSr1YRI)
367
-
368
-- **Docker Runtime**
369
-- **New Messages History and Summarization System**
370
-- **Agent Behavior Change and Management**
371
-- **Text-to-Speech (TTS) and Speech-to-Text (STT)**
372
-- **Settings Page in Web UI**
373
-- **SearXNG Integration Replacing Perplexity + DuckDuckGo**
374
-- **File Browser Functionality**
375
-- **KaTeX Math Visualization Support**
376
-- **In-chat File Attachments**
377
-
378
-### v0.7
379
-[Release video](https://youtu.be/U_Gl0NPalKA)
380
-
381
-- **Automatic Memory**
382
-- **UI Improvements**
383
-- **Instruments**
384
-- **Extensions Framework**
385
-- **Reflection Prompts**
386
-- **Bug Fixes**
387
-
388
-## 🤝 Community and Support
389
-
390
-- [Join our Discord](https://discord.gg/B8KZKNsPpj) for live discussions or [visit our Skool Community](https://www.skool.com/agent-zero).
391
-- [Follow our YouTube channel](https://www.youtube.com/@AgentZeroFW) for hands-on explanations and tutorials
392
-- [Report Issues](https://github.com/agent0ai/agent-zero/issues) for bug fixes and features
knowledge/main/about/identity.md
new
+34
@@ -0,0 +1,34 @@
1
+# Agent Zero - Identity and Design Philosophy
2
+
3
+## What Agent Zero Is
4
+
5
+Agent Zero is an open-source, general-purpose agentic framework. It is not pre-programmed for specific tasks and has no fixed capability set beyond the basics. Its defining characteristic is that it grows and adapts as it is used - accumulating knowledge, solutions, and behaviors through persistent memory and user customization.
6
+
7
+The framework has been created by Jan Tomášek and is maintained by the Agent Zero dev team and the community. Source code lives at github.com/agent0ai/agent-zero.
8
+
9
+## Core Design Principles
10
+
11
+**No hard-coding.** Almost nothing in the framework is fixed in source code. Agent behavior, tool definitions, message templates, and response patterns are all controlled by files in the `prompts/` directory. Changing the prompts changes the agent - fundamentally if needed.
12
+
13
+**Transparency.** Every prompt, every message template, every tool implementation is readable and editable. There are no hidden instructions or black-box behaviors. The agent can be fully audited.
14
+
15
+**Computer as a tool.** Agent Zero does not have a library of pre-built skill functions. Instead, it uses the operating system directly - writing code, running terminal commands, and creating tools on demand. The terminal is the primary interface to everything.
16
+
17
+**Organic growth.** The agent accumulates knowledge through experience. Facts, solutions, discovered patterns, and useful code are stored in memory and recalled in future conversations. The agent becomes more effective at tasks it has done before.
18
+
19
+**Prompt-driven behavior.** The `prompts/` directory is the control plane. System prompts, tool instructions, framework messages, and utility AI prompts are all there. The agent's behavior is as good as its prompts.
20
+
21
+## Project Context
22
+
23
+- **Repository**: github.com/agent0ai/agent-zero
24
+- **License**: Open source
25
+- **Primary author**: Jan Tomášek
26
+- **Community**: Discord (discord.gg/B8KZKNsPpj), Skool community, YouTube channel
27
+- **Documentation**: docs/ folder in the repository; deepwiki.com/agent0ai/agent-zero for AI-generated docs
28
+- **Current version**: v0.9.8
29
+
30
+## Relationship With the User
31
+
32
+Agent Zero treats the human user as its top-level superior in the agent hierarchy. The user is functionally indistinguishable from a superior agent - they give tasks, receive reports, and can intervene at any time. The agent is not a chatbot that answers questions; it is an executor that solves tasks using whatever means are available to it.
33
+
34
+The framework is a personal tool, not a service. It runs locally (or on user-controlled infrastructure) and has access to the user's files, credentials, and systems as configured. This makes it powerful and requires the user to understand what they are delegating.
knowledge/main/about/installation.md
deleted
-585
@@ -1,585 +0,0 @@
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
-## **Goal:** Go from zero to a first working chat with minimal setup.
8
-
9
-
10
-## Step 1: Install Docker Desktop
11
-
12
-Docker Desktop provides the runtime environment for Agent Zero, ensuring consistent behavior and security across platforms. The entire framework runs within a Docker container, providing isolation and easy deployment.
13
-
14
-**Choose your operating system:**
15
-
16
-<table>
17
-<tr>
18
-<td align="center" width="33%">
19
-<a href="#windows-installation">
20
-<img src="../res/setup/oses/windows.png" width="80" alt="Windows"/><br/>
21
-<b>Windows</b>
22
-</a>
23
-</td>
24
-<td align="center" width="33%">
25
-<a href="#macos-installation">
26
-<img src="../res/setup/oses/apple.png" width="80" alt="macOS"/><br/>
27
-<b>macOS</b>
28
-</a>
29
-</td>
30
-<td align="center" width="33%">
31
-<a href="#linux-installation">
32
-<img src="../res/setup/oses/linux.png" width="80" alt="Linux"/><br/>
33
-<b>Linux</b>
34
-</a>
35
-</td>
36
-</tr>
37
-</table>
38
-
39
----
40
-
41
-<a name="windows-installation"></a>
42
-## <img src="../res/setup/oses/windows.png" width="30" alt="Windows"/> Windows Installation
43
-
44
-**1.1. Download Docker Desktop**
45
-
46
-Go to the [Docker Desktop download page](https://www.docker.com/products/docker-desktop/) and download the Windows version (Intel/AMD is the main download button).
47
-
48
-<img src="../res/setup/image-8.png" alt="docker download" width="200"/>
49
-<br><br>
50
-
51
-**1.2. Run the Installer**
52
-
53
-Run the installer with default settings.
54
-
55
-<img src="../res/setup/image-9.png" alt="docker install" width="300"/>
56
-<img src="../res/setup/image-10.png" alt="docker install" width="300"/>
57
-<br><br>
58
-
59
-**1.3. Launch Docker Desktop**
60
-
61
-Once installed, launch Docker Desktop from your Start menu or desktop shortcut.
62
-
63
-<img src="../res/setup/image-11.png" alt="docker installed" height="100"/>
64
-
65
-✅ **Docker is now installed!**
66
-
67
-### Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero)
68
-
69
----
70
-
71
-<a name="macos-installation"></a>
72
-## <img src="../res/setup/oses/apple.png" width="30" alt="macOS"/> macOS Installation
73
-
74
-**1.1. Download Docker Desktop**
75
-
76
-Go to the [Docker Desktop download page](https://www.docker.com/products/docker-desktop/) and download the macOS version (choose Apple Silicon or Intel based on your Mac).
77
-
78
-<img src="../res/setup/image-8.png" alt="docker download" width="200"/>
79
-<br><br>
80
-
81
-**1.2. Install Docker Desktop**
82
-
83
-Drag and drop the Docker application to your Applications folder.
84
-
85
-<img src="../res/setup/image-12.png" alt="docker install" width="300"/>
86
-<br><br>
87
-
88
-**1.3. Launch Docker Desktop**
89
-
90
-Open Docker Desktop from your Applications folder.
91
-
92
-<img src="../res/setup/image-13.png" alt="docker installed" height="100"/>
93
-<br><br>
94
-
95
-**1.4. Configure Docker Socket**
96
-
97
-> [!NOTE]
98
-> **Important macOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings → Advanced, enable "Allow the default Docker socket to be used (requires password)."
99
-
100
-
101
-
102
-✅ **Docker is now installed!**
103
-
104
-### Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero)
105
-
106
----
107
-
108
-<a name="linux-installation"></a>
109
-## <img src="../res/setup/oses/linux.png" width="30" alt="Linux"/> Linux Installation
110
-
111
-**1.1. Choose Installation Method**
112
-
113
-You can install either Docker Desktop or docker-ce (Community Edition).
114
-
115
-**Option A: Docker Desktop (Recommended for beginners)**
116
-
117
-Follow the instructions for your specific Linux distribution [here](https://docs.docker.com/desktop/install/linux-install/).
118
-
119
-**Option B: docker-ce (Lightweight alternative)**
120
-
121
-Follow the installation instructions [here](https://docs.docker.com/engine/install/).
122
-
123
-**1.2. Post-Installation Steps (docker-ce only)**
124
-
125
-If you installed docker-ce, add your user to the `docker` group:
126
-
127
-```bash
128
-sudo usermod -aG docker $USER
129
-```
130
-
131
-Log out and back in, then authenticate:
132
-
133
-```bash
134
-docker login
135
-```
136
-
137
-**1.3. Launch Docker**
138
-
139
-If you installed Docker Desktop, launch it from your applications menu.
140
-
141
-✅ **Docker is now installed!**
142
-
143
-> [!TIP]
144
-> **Deploying on a VPS/Server?** For production deployments with reverse proxy, SSL, and domain configuration, see the [VPS Deployment Guide](vps-deployment.md).
145
-
146
----
147
-
148
-## Step 2: Run Agent Zero
149
-
150
-### 2.1. Pull the Agent Zero Docker Image
151
-
152
-**Using Docker Desktop GUI:**
153
-
154
-- Search for `agent0ai/agent-zero` in Docker Desktop
155
-- Click the `Pull` button
156
-- The image will be downloaded to your machine in a few minutes
157
-
158
-
159
-
160
-**Using Terminal:**
161
-
162
-```bash
163
-docker pull agent0ai/agent-zero
164
-```
165
-
166
-### 2.2. (Optional) Map Folders for Persistence
167
-
168
-Choose or create a folder on your computer where Agent Zero will save its data.
169
-
170
-### Setting up persistence is needed only if you want your data and files to remain available even after you delete the container.
171
-
172
-You can pick any location you find convenient:
173
-
174
-- **Windows:** `C:\agent-zero-data`
175
-- **macOS/Linux:** `/home/user/agent-zero-data`
176
-
177
-You can map just the `/a0/usr` directory (recommended) or individual subfolders of `/a0` to a local directory.
178
-
179
-> [!CAUTION]
180
-> Do **not** map the entire `/a0` directory: it contains the application code and can break upgrades.
181
-
182
-> [!TIP]
183
-> Choose a location that's easy to access and backup. All your Agent Zero data will be directly accessible in this directory.
184
-
185
-### 2.3. Run the Container
186
-
187
-**Using Docker Desktop GUI:**
188
-
189
-- In Docker Desktop, go to the "Images" tab
190
-- Click the `Run` button next to the `agent0ai/agent-zero` image
191
-- Open the "Optional settings" menu
192
-- **Ensure at least one host port is mapped to container port `80`** (set host port to `0` for automatic assignment)
193
-- Click the `Run` button
194
-
195
-
196
-
197
-
198
-The container will start and show in the "Containers" tab:
199
-
200
-
201
-
202
-### 2.4. Access the Web UI
203
-
204
-The framework will take a few seconds to initialize. Find the mapped port in Docker Desktop (shown as `<PORT>:80`) or click the port right under the container ID:
205
-
206
-
207
-
208
-Open `http://localhost:<PORT>` in your browser. The Web UI will open - Agent Zero is ready for configuration!
209
-
210
-
211
-
212
-> [!TIP]
213
-> You can also access the Web UI by clicking the port link directly under the container ID in Docker Desktop.
214
-
215
-> [!NOTE]
216
-> After starting the container, you'll find all Agent Zero files in your chosen directory. You can access and edit these files directly on your machine, and the changes will be immediately reflected in the running container.
217
-
218
-**Running A0 using Terminal?**
219
-
220
-```bash
221
-docker run -p 0:80 -v /path/to/your/work_dir:/a0/usr agent0ai/agent-zero
222
-```
223
-
224
-- Replace `0` with a fixed port if you prefer (e.g., `50080:80`)
225
-
226
----
227
-
228
-## Step 3: Configure Agent Zero
229
-
230
-The UI will show a warning banner "Missing LLM API Key for current settings". Click on `Add your API key` to enter Settings and start configuring A0.
231
-
232
-### Settings Configuration
233
-
234
-Agent Zero provides a comprehensive settings interface to customize various aspects of its functionality. Access the settings by clicking the "Settings" button with a gear icon in the sidebar.
235
-
236
-### Agent Configuration
237
-
238
-- **Agent Profile:** Select the agent profile (e.g., `agent0`, `hacker`, `researcher`). Profiles can override prompts, tools, and extensions.
239
-- **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances.
240
-- **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding.
241
-
242
-> [!NOTE]
243
-> Since v0.9.7, custom prompts belong in `/a0/agents/<agent_name>/prompts/` rather than a shared `/prompts` folder. See the [Extensions guide](../developer/extensions.md#prompts) for details.
244
-
245
-> [!NOTE]
246
-> The Hacker profile is included in the main image. After launch, choose the **hacker** agent profile in Settings if you want the security-focused prompts and tooling. The "hacker" branch is deprecated.
247
-
248
-
249
-
250
-### Chat Model Settings
251
-
252
-- **Provider:** Select the chat model provider (e.g., Anthropic)
253
-- **Model Name:** Choose the specific model (e.g., claude-sonnet-4-5)
254
-- **Context Length:** Set the maximum token limit for context window
255
-- **Context Window Space:** Configure how much of the context window is dedicated to chat history
256
-
257
-
258
-
259
-**Model naming is provider-specific.**
260
-
261
-Use `claude-sonnet-4-5` for Anthropic, but use `anthropic/claude-sonnet-4-5` for OpenRouter. If you see "Invalid model ID," verify the provider and naming format on the provider website, or search the web for "<name-of-ai-model> model naming".
262
-
263
-> [!TIP]
264
-> **Context window tuning:** Set the total context window size first (for example, 100k), then adjust the chat history portion as a fraction of that total. A large fraction on a very large context window can still be enormous.
265
-
266
-> [!TIP]
267
-> **API URL:** URL of the API endpoint for the chat model - only needed for some providers like Ollama, LM Studio, Azure, etc.
268
-
269
-### Utility Model Configuration
270
-
271
-- **Provider & Model:** Select a model for utility tasks like memory organization and summarization
272
-- **Temperature:** Adjust the determinism of utility responses
273
-
274
-> [!NOTE]
275
-> Utility models need to be strong enough to extract and consolidate memory reliably. Very small models (e.g., 4B) often fail at this; 70B-class models or high-quality cloud "flash/mini" models work best.
276
-
277
-### Embedding Model Settings [Optional]
278
-
279
-- **Provider:** Choose the embedding model provider (e.g., OpenAI)
280
-- **Model Name:** Select the specific embedding model (e.g., text-embedding-3-small)
281
-
282
-> [!NOTE]
283
-> Agent Zero uses a local embedding model by default (runs on CPU), but you can switch to OpenAI embeddings like `text-embedding-3-small` or `text-embedding-3-large` if preferred.
284
-
285
-### Speech to Text Options
286
-
287
-- **Model Size:** Choose the speech recognition model size
288
-- **Language Code:** Set the primary language for voice recognition
289
-- **Silence Settings:** Configure silence threshold, duration, and timeout parameters for voice input
290
-
291
-### API Keys
292
-
293
-Configure API keys for various service providers directly within the Web UI. Click `Save` to confirm your settings.
294
-
295
-> [!NOTE]
296
-> **OpenAI API vs Plus subscription:** A ChatGPT Plus subscription does not include API credits. You must provide a separate API key for OpenAI usage in Agent Zero.
297
-
298
-> [!TIP]
299
-> For OpenAI-compatible providers (e.g., custom gateways or Z.AI/GLM), add the API key under **External Services → Other OpenAI-compatible API keys**, then select **OpenAI Compatible** as the provider in model settings.
300
-
301
-> [!CAUTION]
302
-> **GitHub Copilot Provider:** When using the GitHub Copilot provider, after selecting the model and entering your first prompt, the OAuth login procedure will begin. You'll find the authentication code and link in the output logs. Complete the authentication process by following the provided link and entering the code, then you may continue using Agent Zero.
303
-
304
-### Authentication
305
-
306
-- **UI Login:** Set username for web interface access
307
-- **UI Password:** Configure password for web interface security
308
-- **Root Password:** Manage Docker container root password for SSH access
309
-
310
-
311
-
312
-### Development Settings
313
-
314
-- **RFC Parameters (local instances only):** Configure URLs and ports for remote function calls between instances
315
-- **RFC Password:** Configure password for remote function calls
316
-
317
-Learn more about Remote Function Calls in the [Development Setup guide](dev-setup.md#step-6-configure-ssh-and-rfc-connection).
318
-
319
-> [!IMPORTANT]
320
-> Always keep your API keys and passwords secure.
321
-
322
-> [!NOTE]
323
-> On Windows host installs (non-Docker), you must use RFC to run shell code on the host system. The Docker runtime handles this automatically.
324
-
325
----
326
-
327
-## Choosing Your LLMs
328
-
329
-The Settings page is the control center for selecting the Large Language Models (LLMs) that power Agent Zero. You can choose different LLMs for different roles:
330
-
331
-| LLM Role | Description |
332
-| --- | --- |
333
-| `chat_llm` | This is the primary LLM used for conversations and generating responses. |
334
-| `utility_llm` | This LLM handles internal tasks like summarizing messages, managing memory, and processing internal prompts. Using a smaller, less expensive model here can improve efficiency. |
335
-| `browser_llm` | This LLM powers the browser agent for web navigation and interaction tasks. Vision support is recommended for better page understanding. |
336
-| `embedding_llm` | The embedding model shipped with A0 runs on CPU and is responsible for generating embeddings used for memory retrieval and knowledge base lookups. Changing the `embedding_llm` will re-index all of A0's memory. |
337
-
338
-**How to Change:**
339
-
340
-1. Open Settings page in the Web UI.
341
-2. Choose the provider for the LLM for each role (Chat model, Utility model, Browser model, Embedding model) and write the model name.
342
-3. Click "Save" to apply the changes.
343
-
344
-### Important Considerations
345
-
346
-#### Model Naming by Provider
347
-
348
-Use the naming format required by your selected provider:
349
-
350
-| Provider | Model Name Format | Example |
351
-| --- | --- | --- |
352
-| OpenAI | Model name only | `claude-sonnet-4-5` |
353
-| OpenRouter | Provider prefix mostly required | `anthropic/claude-sonnet-4-5` |
354
-| Ollama | Model name only | `gpt-oss:20b` |
355
-
356
-> [!TIP]
357
-> If you see "Invalid model ID," verify the provider and naming format on the provider website, or search the web for "<name-of-ai-model> model naming".
358
-
359
-#### Context Window & Memory Split
360
-
361
-- Set the **total context window** (e.g., 100k) first.
362
-- Then tune the **chat history portion** as a fraction of that total.
363
-- Extremely large totals can make even small fractions very large; adjust thoughtfully.
364
-
365
-#### Utility Model Guidance
366
-
367
-- Utility models handle summarization and memory extraction.
368
-- Very small models (≈4B) usually fail at reliable context extraction.
369
-- Aim for ~70B class models or strong cloud "flash/mini" models for better results.
370
-
371
-#### Reasoning/Thinking Models
372
-
373
-- Reasoning can increase cost and latency. Some models perform better **without** reasoning.
374
-- If a model supports it, disable reasoning via provider-specific parameters (e.g., Venice `disable_thinking=true`).
375
-
376
----
377
-
378
-## Installing and Using Ollama (Local Models)
379
-
380
-Ollama is a powerful tool that allows you to run various large language models locally.
381
-
382
----
383
-
384
-<a name="windows-ollama-installation"></a>
385
-### <img src="../res/setup/oses/windows.png" width="30" alt="Windows"/> Windows Ollama Installation
386
-
387
-Download and install Ollama from the official website:
388
-
389
-<button>[Download Ollama Setup](https://ollama.com/download/OllamaSetup.exe)</button>
390
-
391
-Once installed, continue to [Pulling Models](#pulling-models).
392
-
393
----
394
-
395
-<a name="macos-ollama-installation"></a>
396
-### <img src="../res/setup/oses/apple.png" width="30" alt="macOS"/> macOS Ollama Installation
397
-
398
-**Using Homebrew:**
399
-
400
-```bash
401
-brew install ollama
402
-```
403
-
404
-**Using Installer:**
405
-
406
-Download from the [official website](https://ollama.com/).
407
-
408
-Once installed, continue to [Pulling Models](#pulling-models).
409
-
410
----
411
-
412
-<a name="linux-ollama-installation"></a>
413
-### <img src="../res/setup/oses/linux.png" width="30" alt="Linux"/> Linux Ollama Installation
414
-
415
-Run the installation script:
416
-
417
-```bash
418
-curl -fsSL https://ollama.com/install.sh | sh
419
-```
420
-
421
-Once installed, continue to [Pulling Models](#pulling-models).
422
-
423
----
424
-
425
-### Pulling Models
426
-
427
-**Finding Model Names:**
428
-
429
-Visit the [Ollama model library](https://ollama.com/library) for a list of available models and their corresponding names. Ollama models are referenced by **model name only** (for example, `llama3.2`).
430
-
431
-**Pull a model:**
432
-
433
-```bash
434
-ollama pull <model-name>
435
-```
436
-
437
-Replace `<model-name>` with the name of the model you want to use. For example: `ollama pull mistral-large`
438
-
439
-### Configuring Ollama in Agent Zero
440
-
441
-1. Once you've downloaded your model(s), select it in the Settings page of the GUI.
442
-2. Within the Chat model, Utility model, or Embedding model section, choose **Ollama** as provider.
443
-3. Write your model code as expected by Ollama, in the format `llama3.2` or `qwen2.5:7b`
444
-4. Provide your API base URL to your Ollama API endpoint, usually `http://host.docker.internal:11434`
445
-5. Click `Save` to confirm your settings.
446
-
447
-
448
-
449
-> [!NOTE]
450
-> If Agent Zero runs in Docker and Ollama runs on the host, ensure port **11434** is reachable from the container. If both services are in the same Docker network, you can use `http://<container_name>:11434` instead of `host.docker.internal`.
451
-
452
-### Managing Downloaded Models
453
-
454
-**Listing downloaded models:**
455
-
456
-```bash
457
-ollama list
458
-```
459
-
460
-**Removing a model:**
461
-
462
-```bash
463
-ollama rm <model-name>
464
-```
465
-
466
-> [!TIP]
467
-> Experiment with different model combinations to find the balance of performance and cost that best suits your needs. E.g., faster and lower latency LLMs will help, and you can also use `faiss_gpu` instead of `faiss_cpu` for the memory.
468
-
469
----
470
-
471
-## How to Update Agent Zero
472
-
473
-> [!NOTE]
474
-> Since v0.9, Agent Zero includes a Backup & Restore workflow in the Settings UI. This is the **safest** way to upgrade Docker instances.
475
-
476
-### Recommended Update Process (Docker)
477
-
478
-1. **Keep the old container running** and note its port.
479
-2. **Pull the new image** (`agent0ai/agent-zero:latest`).
480
-3. **Start a new container** on a different host port.
481
-4. In the **old** instance, open **Settings → Backup & Restore** and create a backup.
482
-5. In the **new** instance, restore that backup from the same panel.
483
-
484
-> [!TIP]
485
-> If the new instance fails to load settings, remove `/a0/usr/settings.json` and restart to regenerate default settings.
486
-
487
----
488
-
489
-## Using Agent Zero on Your Mobile Device
490
-
491
-Agent Zero can be accessed from mobile devices and other computers using the built-in **Tunnel feature**.
492
-
493
-### Recommended: Using Tunnel (Remote Access)
494
-
495
-The Tunnel feature allows secure access to your Agent Zero instance from anywhere:
496
-
497
-1. Open Settings in the Web UI
498
-2. Navigate to the **External Services** tab
499
-3. Click on **Flare Tunnel** in the navigation menu
500
-4. Click **Create Tunnel** to generate a secure HTTPS URL
501
-5. Share this URL to access Agent Zero from any device
502
-
503
-> [!IMPORTANT]
504
-> **Security:** Always set a username and password in Settings → Authentication before creating a tunnel to secure your instance on the internet.
505
-
506
-For complete details on tunnel configuration and security considerations, see the [Remote Access via Tunneling](../guides/usage.md#remote-access-via-tunneling) section in the Usage Guide.
507
-
508
-### Alternative: Local Network Access
509
-
510
-If you prefer to keep access limited to your local network:
511
-
512
-1. Find the mapped port in Docker Desktop (format: `<PORT>:80`, e.g., `32771:80`)
513
-2. Access from the same computer: `http://localhost:<PORT>`
514
-3. Access from other devices on the network: `http://<YOUR_COMPUTER_IP>:<PORT>`
515
-
516
-> [!TIP]
517
-> Find your computer's IP address with `ipconfig` (Windows) or `ifconfig`/`ip addr` (macOS/Linux). It's usually in the format `192.168.x.x` or `10.0.x.x`.
518
-
519
-For developers or users who need to run Agent Zero directly on their system, see the [In-Depth Guide for Full Binaries Installation](dev-setup.md).
520
-
521
----
522
-
523
-## Advanced: Automated Configuration via Environment Variables
524
-
525
-Agent Zero settings can be automatically configured using environment variables with the `A0_SET_` prefix in your `.env` file. This enables automated deployments without manual configuration.
526
-
527
-**Usage:**
528
-
529
-Add variables to your `.env` file in the format:
530
-
531
-```env
532
-A0_SET_{setting_name}={value}
533
-```
534
-
535
-**Examples:**
536
-
537
-```env
538
-# Model configuration
539
-A0_SET_chat_model_provider=anthropic
540
-A0_SET_chat_model_name=claude-3-5-sonnet-20241022
541
-A0_SET_chat_model_ctx_length=200000
542
-
543
-# Memory settings
544
-A0_SET_memory_recall_enabled=true
545
-A0_SET_memory_recall_interval=5
546
-
547
-# Agent configuration
548
-A0_SET_agent_profile=custom
549
-A0_SET_agent_memory_subdir=production
550
-```
551
-
552
-**Docker usage:**
553
-
554
-When running Docker, you can pass these as environment variables:
555
-
556
-```bash
557
-docker run -p 50080:80 \
558
- -e A0_SET_chat_model_provider=anthropic \
559
- -e A0_SET_chat_model_name=claude-3-5-sonnet-20241022 \
560
- agent0ai/agent-zero
561
-```
562
-
563
-**Notes:**
564
-
565
-- These provide initial default values when settings.json doesn't exist or when new settings are added to the application. Once a value is saved in settings.json, it takes precedence over these environment variables.
566
-- Sensitive settings (API keys, passwords) use their existing environment variables
567
-- Container/process restart required for changes to take effect
568
-
569
----
570
-
571
-### Manual Migration (Legacy or Non-Docker)
572
-
573
-If you are migrating from older, non-Docker setups, A0 handles the migration of legacy folders and files automatically at runtime. The right place to save your files and directories is `a0/usr`.
574
-
575
-## Conclusion
576
-
577
-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.
578
-
579
-**Next Steps:**
580
-
581
-- For production server deployments, see the [VPS Deployment Guide](vps-deployment.md)
582
-- For development setup and extensions, see the [Development Setup Guide](dev-setup.md)
583
-- For remote access via tunnel, see [Remote Access via Tunneling](../guides/usage.md#remote-access-via-tunneling)
584
-
585
-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.
knowledge/main/about/setup-and-deployment.md
new
+110
@@ -0,0 +1,110 @@
1
+# Agent Zero - Setup and Deployment
2
+
3
+## Docker Deployment (Standard)
4
+
5
+Agent Zero is distributed as a Docker image: `agent0ai/agent-zero`.
6
+
7
+```bash
8
+docker pull agent0ai/agent-zero
9
+docker run -p 50001:80 agent0ai/agent-zero
10
+```
11
+
12
+The web UI is then accessible at `http://localhost:50001`. The container exposes port 80 internally; map any host port to it.
13
+
14
+## Persistence
15
+
16
+All user data lives in `/a0/usr/` inside the container. Without a volume mount, data is lost when the container is removed.
17
+
18
+Map `/a0/usr` to a host directory for persistence:
19
+```bash
20
+docker run -p 50001:80 -v /path/on/host:/a0/usr agent0ai/agent-zero
21
+```
22
+
23
+Contents of `/a0/usr/`:
24
+- `settings.json` - all configuration including API keys and model settings
25
+- `memory/` - FAISS vector indexes and knowledge import state
26
+- `knowledge/` - user-added knowledge files
27
+- `agents/` - custom agent profiles
28
+- `plugins/` - user plugins
29
+- `projects/` - project workspaces
30
+- `work/` - default working directory for agent file output
31
+
32
+## Configuration After Start
33
+
34
+On first run, open Settings (gear icon) and configure:
35
+1. **API Keys** - add at least one provider API key under the relevant provider section
36
+2. **Chat Model** - select provider and model name for the primary LLM
37
+3. **Utility Model** - select a cheaper/faster model for internal tasks
38
+4. **Embedding Model** - select embedding provider and model (required for memory and knowledge)
39
+
40
+Settings are saved to `usr/settings.json` immediately on change.
41
+
42
+## Updating Agent Zero
43
+
44
+The recommended update process preserves user data:
45
+1. Keep the old container running
46
+2. Pull the new image: `docker pull agent0ai/agent-zero`
47
+3. Start the new container on a different host port
48
+4. In the old instance: Settings → Backup & Restore → Create Backup
49
+5. In the new instance: Settings → Backup & Restore → Restore from Backup
50
+6. Stop the old container
51
+
52
+## Remote Access
53
+
54
+### Flare Tunnel (recommended for external access)
55
+Settings → External Services → Flare Tunnel → Create Tunnel
56
+
57
+This generates a public HTTPS URL without requiring firewall changes or a static IP. Set a username and password before creating the tunnel to enable authentication.
58
+
59
+### Local Network
60
+Access from other devices on the same network using the host machine's IP:
61
+`http://<host-ip>:<mapped-port>`
62
+
63
+### Microsoft Dev Tunnels
64
+Supported as an alternative to Flare for users in Microsoft environments. Configure under External Services in Settings.
65
+
66
+## Mobile Access
67
+
68
+Agent Zero is a Progressive Web App (PWA). On mobile, open the web UI URL in a browser, then add to home screen for an app-like experience. Works with both local network and tunnel URLs.
69
+
70
+## Common Troubleshooting
71
+
72
+**Agent responds but no memory/knowledge recall:**
73
+- Check that an embedding model is configured (provider + model name)
74
+- Verify the embedding provider API key is set
75
+- Embedding model changes require re-indexing; this happens automatically but takes time on first run
76
+
77
+**"Model not found" or API errors:**
78
+- Verify the model name matches the provider's naming convention exactly
79
+- Check that the API key has access to the requested model
80
+- For OpenRouter, model names must include the provider prefix (`anthropic/claude-sonnet-4-5`)
81
+
82
+**Container starts but web UI unreachable:**
83
+- Confirm the host port mapping in `docker ps`
84
+- Check that no firewall rule blocks the mapped port
85
+- The container needs a few seconds to initialize on first start
86
+
87
+**Knowledge files not being recalled:**
88
+- Supported formats: `.md`, `.txt`, `.pdf`, `.csv`, `.html`, `.json`
89
+- Files must be in `knowledge/` (framework level) or `usr/knowledge/<subdir>/`
90
+- The configured `agent_knowledge_subdir` must match the subdir where files are placed
91
+- Re-indexing is triggered automatically when file checksums change
92
+
93
+**Ollama / local model setup:**
94
+- Ollama must be running and accessible from inside the Docker container
95
+- Use `http://host.docker.internal:<port>` as the API URL for Ollama (not `localhost`)
96
+- Pull the model first: `ollama pull <model-name>`
97
+
98
+## Development Setup (non-Docker)
99
+
100
+```bash
101
+git clone https://github.com/agent0ai/agent-zero
102
+cd agent-zero
103
+python -m venv .venv
104
+source .venv/bin/activate
105
+pip install -r requirements.txt
106
+pip install -r requirements2.txt
107
+python run_ui.py
108
+```
109
+
110
+The dev server runs on `http://localhost:5000` by default. User data is written to `usr/` in the project root.
skills/a0-create-plugin/SKILL.md
+33
@@ -158,6 +158,9 @@ If your plugin exposes existing core settings rather than plugin-specific ones,
158
### Import Paths
159
- Correct: `from agent import AgentContext, AgentContextType`
160
- Correct: `from initialize import initialize_agent`
161
+- Correct for plugin-local Python modules under `usr/plugins/<name>/`: `from usr.plugins.<name>.helpers.module import ...`
162
+- Avoid `sys.path` hacks for plugin-local imports
163
+- Avoid symlink-dependent imports like `from plugins.<name>...` for user/community plugins in `usr/plugins/`
164
165
### Sending Messages Proactively
166
```python
@@ -209,6 +212,29 @@ save_plugin_config(
212
my-store.js # Alpine stores
213
```
214
215
+### Import rule for plugin-local Python code
216
+
217
+Use the fully qualified `usr.plugins.<plugin_name>...` path for plugin-local
218
+imports. This lets plugins keep a normal `helpers/` directory without renaming
219
+it to `<name>_helpers`, and it avoids both `sys.path` mutation and symlink
220
+installation steps.
221
+
222
+Good:
223
+
224
+```python
225
+from usr.plugins.my_plugin.helpers.runtime import do_work
226
+import usr.plugins.my_plugin.helpers.state as state
227
+```
228
+
229
+Avoid:
230
+
231
+```python
232
+sys.path.insert(0, ...)
233
+from helpers.runtime import do_work
234
+
235
+from plugins.my_plugin.helpers.runtime import do_work
236
+```
237
+
238
## Plugin Execution Script (`execute.py`)
239
If your plugin needs a user-triggered script for setup, post-install work, maintenance, or other manual operations, add an `execute.py` at the plugin root.
240
@@ -221,6 +247,12 @@ Good uses for `execute.py` include:
247
248
Use `execute.py` for **user-initiated** work. If the behavior is framework-internal or should happen automatically as part of plugin lifecycle handling, use `hooks.py` or lifecycle extensions instead.
249
250
+First rule of plugin side effects: do not modify the system permanently in ways
251
+that outlive the plugin. When a plugin is deleted, there should be no leftover
252
+symlinks, unmanaged services, or stray files outside plugin-owned paths unless
253
+the user explicitly requested that behavior and the plugin documents how to
254
+clean it up.
255
+
256
```python
257
import subprocess
258
import sys
@@ -254,6 +286,7 @@ If your plugin needs framework-internal hook points, add a `hooks.py` file at th
286
- Use it for things like install hooks, plugin registration work, cache setup, file preparation, or other internal framework operations.
287
- Hook functions may be sync or async.
288
- Current example: the plugin installer calls `install()` in `hooks.py` after placing a plugin in `usr/plugins/`.
289
+- Hooks should be reversible and cleanup-safe. Prefer framework-managed state and plugin-owned paths over permanent system modifications.
290
291
### Environment targeting rules
292
- If `hooks.py` runs `sys.executable -m pip install ...`, it installs into the same Python environment that is running Agent Zero.