| 1 | # Architecture And Runtime |
| 2 | |
| 3 | ## Source Anchors |
| 4 | |
| 5 | - Root contract: `/a0/AGENTS.md` |
| 6 | - WebUI entry point: `/a0/run_ui.py` |
| 7 | - Runtime arguments and WebUI port resolution: `/a0/helpers/runtime.py` |
| 8 | - Docker Python runtimes: `/a0/docker/base/fs/ins/install_python.sh` |
| 9 | - Docker framework activation: `/a0/docker/run/fs/ins/setup_venv.sh` |
| 10 | - Docker UI launch manager: `/a0/docker/run/fs/exe/self_update_manager.py` |
| 11 | - Search/discovery roots: `/a0/helpers/subagents.py`, `/a0/helpers/skills.py`, `/a0/helpers/projects.py` |
| 12 | |
| 13 | ## Runtime Split |
| 14 | |
| 15 | Agent Zero has two Docker Python runtimes: |
| 16 | |
| 17 | | Runtime | Python | Purpose | |
| 18 | |---|---|---| |
| 19 | | `/opt/venv-a0` | 3.12.4 | Framework runtime. Runs the WebUI backend, API, scheduler, agent loop, framework imports, plugin hooks, and framework-side tools. | |
| 20 | | `/opt/venv` | 3.13 | Agent execution runtime. Use for Python code executed on behalf of the agent or user task dependencies. | |
| 21 | |
| 22 | Use `/opt/venv-a0` for framework import checks, WebUI startup checks, API/plugin hook behavior, and `py_compile` of framework code inside Docker. Use `/opt/venv` only when the feature explicitly targets agent/user code execution. |
| 23 | |
| 24 | Do not claim a package works in the framework because it imports in `/opt/venv`, and do not claim user-code execution works because it imports in `/opt/venv-a0`. |
| 25 | |
| 26 | ## Ports And URLs |
| 27 | |
| 28 | Do not hardcode a WebUI default port in guidance. Discover the effective URL from: |
| 29 | |
| 30 | - WebUI startup output. |
| 31 | - Launcher or Docker published-port mapping. |
| 32 | - Explicit `--host` and `--port` arguments. |
| 33 | - `WEB_UI_HOST` and `WEB_UI_PORT` environment configuration. |
| 34 | - Live container inspection when the task targets a running runtime. |
| 35 | |
| 36 | `helpers.runtime.get_web_ui_port()` has a code fallback, and the Docker UI manager passes an internal container port. Those are implementation details, not a stable user-facing URL contract. |
| 37 | |
| 38 | ## Root Paths |
| 39 | |
| 40 | - `/a0/` means the framework root inside the Docker runtime. |
| 41 | - In a local checkout, `/a0/` in documentation maps to the repository root. |
| 42 | - `usr/` contains user state, projects, settings, skills, plugins, chats, and workdirs. |
| 43 | - `tmp/` contains runtime caches and generated working files. |
| 44 | - Do not document ignored `usr/` or `tmp/` changes unless explicitly asked. |
| 45 | |
| 46 | When the user names a live Dockerized runtime, the live `/a0` tree is a separate artifact. Verify the file sync or runtime state directly before treating checkout code as live behavior. |
| 47 | |
| 48 | ## Project Layout |
| 49 | |
| 50 | Key root areas: |
| 51 | |
| 52 | | Path | Purpose | |
| 53 | |---|---| |
| 54 | | `agent.py` | `Agent`, `AgentContext`, `AgentConfig`, prompt reading, tool loop. | |
| 55 | | `initialize.py` | Framework initialization and background loop startup. | |
| 56 | | `models.py` | Model provider and LiteLLM transport configuration. | |
| 57 | | `run_ui.py` | Flask/Socket.IO ASGI WebUI startup. | |
| 58 | | `api/` | HTTP API handlers and `ws_*.py` WebSocket handlers. | |
| 59 | | `helpers/` | Shared framework utilities and base contracts. | |
| 60 | | `tools/` | Core tool implementations. | |
| 61 | | `extensions/` | Built-in backend and WebUI extension points. | |
| 62 | | `plugins/` | Bundled system plugins. | |
| 63 | | `agents/` | Bundled agent profiles. | |
| 64 | | `prompts/` | Core prompt fragments. | |
| 65 | | `skills/` | Bundled skills. | |
| 66 | | `webui/` | Alpine.js frontend shell, components, CSS, assets, and vendor code. | |
| 67 | |
| 68 | ## Discovery Order |
| 69 | |
| 70 | Agent-specific path resolution is handled by `helpers.subagents.get_paths(...)`. In broad terms, project and user/profile paths have higher priority than plugin and bundled defaults, then user root/plugin roots, then base defaults. Inspect `helpers/subagents.py` for exact order before changing discovery behavior. |
| 71 | |
| 72 | Skill discovery is handled by `helpers.skills.get_skill_roots(...)`. Skills may come from bundled `skills/`, user `usr/skills/`, project metadata, agent profile folders, and plugin roots. Loaded skills can expose additional files via `skills_tool action=read_file`. |
| 73 | |
| 74 | ## Development Bias |
| 75 | |
| 76 | - Prefer plugins for new capabilities. |
| 77 | - Prefer `helpers/` only for reusable framework behavior. |
| 78 | - Prefer small, source-backed changes over broad rewrites. |
| 79 | - If an example conflicts with source discovery code or DOX, treat the example as stale until verified. |