README.md · samitouri/QOSami_Agents_Zero-1

Code Commits Issues Pulls Sessions CI/CD

main

md 313 lines 19.3 KB

Rendered Raw

1	<div align="center">
2
3	<img src="docs/res/a0-vector-graphics/horizontal_banner.svg" alt="Agent Zero Banner" width="100%"/>
4
5	# Agent Zero
6	### Give your agent a full Linux computer.
7
8	Agent Zero is an open agent framework for work that needs more than chat: a Dockerized Linux desktop, a browser with DOM annotation, live document cowork, projects, skills, plugins, and a bridge back to your host machine.
9
10	[![Website](https://img.shields.io/badge/Website-agent--zero.ai-0A192F?style=for-the-badge&logo=vercel&logoColor=white)](https://agent-zero.ai)
11	[![Docs](https://img.shields.io/badge/Docs-Read%20the%20guides-1F6FEB?style=for-the-badge&logo=readthedocs&logoColor=white)](./docs/)
12	[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/B8KZKNsPpj)
13	[![GitHub Sponsors](https://img.shields.io/badge/Sponsors-Thank%20you-FF69B4?style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/agent0ai)
14	[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/agent0ai/agent-zero)
15
16	[Quick Start](#quick-start) \|
17	[Why Agent Zero](#why-agent-zero) \|
18	[Try These First](#try-these-first) \|
19	[Deep Dives](#deep-dives) \|
20	[Docs](#documentation)
21
22	</div>
23
24	<div align="center">
25	<img alt="Agent Zero driving Blender in its built-in XFCE desktop" src="docs/res/usage/webui/agentzero-xfce-computer.gif" width="100%" />
26	</div>
27
28	# Why Agent Zero
29
30	\| Feature \| Why it matters \|
31	\| --- \| --- \|
32	\| Full Linux desktop \| The agent can use real GUI software, terminals, files, and desktop apps inside the Canvas. \|
33	\| Browser DOM annotation \| Click page elements and turn them into inspect, change, lift, or review instructions. \|
34	\| Live document cowork \| Edit Markdown, Writer, Spreadsheet, and Presentation files together instead of losing work in chat. \|
35	\| Plugin Hub \| Install 100+ community plugins or publish your own extension points. \|
36	\| Projects and memory \| Keep files, instructions, secrets, memories, repositories, and model-preset choices isolated per project. \|
37	\| Host-machine bridge \| Connect with the A0 CLI so the same agent can work in your real local repositories. \|
38	\| Multi-agent cooperation \| Let agents delegate research, coding, analysis, or review tasks to focused subagents. \|
39	\| Transparent internals \| Prompts, tools, plugins, skills, and settings are inspectable and editable. \|
40
41	# Quick Start
42
43	## Recommended: A0 Launcher
44
45	The desktop A0 Launcher is the fastest guided path on a personal machine. Download it, open it, and let it check Docker, create Instances, manage ports, and connect to local or remote Agent Zero installs.
46
47	Agent Zero runs wherever Docker runs, from a $6 VPS or Raspberry Pi to a local workstation or GPU server.
48
49	\| Architecture \| macOS \| Linux \| Windows \|
50	\| --- \| --- \| --- \| --- \|
51	\| x86 \| [Mac Intel](https://github.com/agent0ai/a0-launcher/releases/download/v1.6/a0-launcher-1.6-macos-x64.dmg) \| [Linux x86](https://github.com/agent0ai/a0-launcher/releases/download/v1.6/a0-launcher-1.6-linux-x64.AppImage) \| [Windows x86](https://github.com/agent0ai/a0-launcher/releases/download/v1.6/a0-launcher-1.6-windows-x64.exe) \|
52	\| ARM64 \| [Mac Apple Silicon](https://github.com/agent0ai/a0-launcher/releases/download/v1.6/a0-launcher-1.6-macos-arm64.dmg) \| [Linux ARM64](https://github.com/agent0ai/a0-launcher/releases/download/v1.6/a0-launcher-1.6-linux-arm64.AppImage) \| [Windows ARM64](https://github.com/agent0ai/a0-launcher/releases/download/v1.6/a0-launcher-1.6-windows-arm64.exe) \|
53
54	See the [A0 Launcher v1.6 release](https://github.com/agent0ai/a0-launcher/releases/tag/v1.6) for release notes and updater metadata. See the [Launcher guide](./docs/guides/launcher.md) for the first-run walkthrough.
55
56	<details>
57	<summary><strong>Other install paths</strong></summary>
58
59	## A0 Install
60
61	Use A0 Install when you want the terminal path: SSH sessions, servers, recovery shells, or a scriptable setup. It creates Dockerized Agent Zero instances, mounts each instance's data into `/a0/usr` inside the container, and uses a reuse-before-setup policy: it tries your current Docker CLI configuration, `DOCKER_HOST`, Docker contexts, and known local Docker-compatible endpoints before setting up a runtime.
62
63	### macOS / Linux
64
65	```bash
66	curl -fsSL https://bash.agent-zero.ai \| bash
67	```
68
69	### Windows PowerShell
70
71	```powershell
72	irm https://ps.agent-zero.ai \| iex
73	```
74
75	### Headless / scripted
76
77	For servers and automation, run the installer in Quick Start mode so it creates one instance and exits without opening menus:
78
79	```bash
80	curl -fsSL https://bash.agent-zero.ai \| bash -s -- --quick-start --name agent-zero --port 5080
81	```
82
83	```powershell
84	& ([scriptblock]::Create((irm https://ps.agent-zero.ai))) -QuickStart -Name agent-zero -Port 5080
85	```
86
87	Use `--skip-runtime-setup` / `-SkipRuntimeSetup` when Docker must already be working and the installer should not try to set up a runtime. See the [A0 Install repository](https://github.com/agent0ai/a0-install) for all installer flags.
88
89	## Docker already installed? Run this directly
90
91	```bash
92	docker run -p 80:80 -v a0_usr:/a0/usr agent0ai/agent-zero
93	```
94
95	Open the Web UI, configure your LLM provider, and start with a concrete task. For the full setup and onboarding experience, see the [Installation guide](./docs/setup/installation.md).
96
97	</details>
98
99	## Troubleshooting
100
101	- Docker is not running: start Docker Desktop or your Docker service, then reopen the Launcher or rerun the install command.
102	- Port 80 is already in use: use the Launcher to pick another port, or run Docker directly with `-p 5080:80` and open `http://localhost:5080`.
103	- Installing on a server: use the A0 Install Quick Start command with `--quick-start --name agent-zero --port 5080`.
104	- Still blocked: see the [Troubleshooting guide](./docs/guides/troubleshooting.md).
105
106	# Try These First
107
108	- Annotate a design you like: "Open this template site in the Browser. I'll annotate the hero section - re-implement it in my project's React + Tailwind stack."
109	- Cowork on a spreadsheet: "Create an editable ODS budget model with assumptions and monthly projections."
110	- Drive a desktop app: "Use the Linux Desktop to open Blender and create a simple 3D logo for me."
111	- Review a web UI: "Open my local app in the Browser. I will annotate the page with comments; then implement the requested UI fixes."
112	- Create a specialist: "Create an Agent Profile for financial analysis with cautious reasoning, clear assumptions, and spreadsheet-first deliverables."
113	- Recover a workspace: "Show me recent Time Travel snapshots and explain what changed before I revert anything."
114
115	# Deep Dives
116
117	## A Real Linux Desktop in the Canvas
118
119	Agent Zero opens its own Linux desktop inside the right-side Canvas. Not a remote VM, not a shared clipboard, but a real XFCE desktop session running in the container.
120
121	That means the agent can drive real desktop software: open Blender to model a 3D object, jump into a terminal window, manage files visually, run a GUI tool that has no API.
122
123	You watch every action, and you can intervene at any moment because your mouse and keyboard share the same desktop.
124
125	See the [Desktop guide](./docs/guides/desktop.md) for the walkthrough, prompt examples, and how Desktop differs from Browser.
126
127	## Native Browser With DOM Annotations
128
129	<img alt="Annotating a webpage element in the Agent Zero browser" src="docs/res/usage/browser/annotation.gif" />
130	<br>
131
132	Agent Zero ships a built-in Browser with an optional live surface in the Canvas. The agent can open pages, read them, click, type, upload files, and take screenshots - the usual. The unusual part is Annotate mode.
133
134	Annotate mode turns any webpage into an interactive directive surface. Click an element to:
135
136	- Change it - "make this button blue and round the corners" runs as a JS instruction the agent applies and verifies.
137	- Inspect it - pull the DOM, the styles, the parent chain, the framework hints into the conversation.
138	- Lift it - see a card, hero, or component on someone else's site that you like? Capture it and have the agent re-implement it in your own project's stack.
139	- Comment it - leave actionable notes pinned to elements during a UI review; the agent reads the comments and ships the fixes.
140
141	The Docker browser is the default live Browser surface. Browser history keeps screenshots of important steps, so older chats can still show what the agent saw. The Browser also supports Chrome extensions inside the Docker browser, and Bring Your Own Browser through the A0 CLI Connector lets the agent drive Chrome, Edge, Brave, Opera, Vivaldi, or Chromium on your own machine.
142
143	See the [Browser guide](./docs/guides/browser.md) for screenshots, settings, host-browser setup, and troubleshooting.
144
145	## Cowork on Documents
146
147	### Markdown Editor With Live Cowork
148
149	<img alt="Agent Zero writing a TODO plan in the Canvas markdown editor" src="docs/res/usage/webui/markdown-editor.gif" />
150	<br>
151
152	The Canvas includes a rich Markdown editor designed for genuine cowork. Ask the agent to "write a plan to do X in a TODO.md in the open doc" and you'll see the file appear in the editor, character by character, while you keep typing in another section.
153
154	It's not a preview pane. It's a real editor with toolbar, formatting buttons, tables, and an editable source view - built so that the agent's edits and yours are equal first-class operations on the same document.
155
156	Use it for plans, TODOs, meeting notes, RFCs, project handoffs, or any artifact where the deliverable should live as text rather than be trapped inside chat scrollback.
157
158	### LibreOffice Integration
159
160	LibreOffice Writer, Calc, and Impress are wired up so you can type by hand while Agent Zero creates, updates, saves, and verifies the same files in real time.
161
162	ODT, ODS, and ODP binary formats are first-class citizens in the Agent Zero Desktop environment to align with the Open Document Format (ODF).
163
164	Use the Desktop toolbar to create and edit Writer, Spreadsheet, and Presentation LibreOffice files.
165
166	## Plugin Hub - 100+ Community Plugins
167
168	<img alt="Agent Zero Plugin Hub showing community plugins" src="docs/res/usage/plugins/plugin-hub-browse.png" />
169	<br>
170
171	Agent Zero is built for extension, not just configuration. The built-in Plugin Hub browses a growing catalog of community plugins - currently more than 100, covering:
172
173	- Development frameworks like the [BMAD Method](https://github.com/bmad-code-org/bmad-method) (full software development lifecycle with 20 specialist agents) and [Agent Skills](https://github.com/addyosmani/agent-skills).
174	- Memory systems - alternative memory backends, intelligent consolidation strategies, vector recall plugins.
175	- Tools and integrations - embedded terminals, custom browsers, deployment helpers, API clients.
176	- UI extensions - chat rename controls, sidebar tweaks, theme packs, custom Canvas panels.
177	- Workflow plugins - schedulers, multi-agent orchestration, project automations.
178
179	Install with a click from the Web UI, or publish your own to the index repository. Combined with custom prompts in `prompts/`, custom tools in `tools/`, MCP servers, A2A connectors, and project-scoped configuration, Agent Zero gives you a real surface area to shape the agent into whatever you need.
180
181	See the [Skills guide](./docs/guides/skills.md), the [Create a Small Plugin](./docs/guides/create-plugin.md) tutorial, and the [MCP setup](./docs/guides/mcp-setup.md) guide.
182
183	## Use Your OpenAI Codex Plan
184
185	<img alt="OAuth LLM plans in Agent Zero" src="docs/res/codex-screenshot.png" />
186	<br>
187
188	Agent Zero connects to your OpenAI Codex plan through the new OAuth flow. Sign in with your account, pick the Codex-backed provider, and let Agent Zero use the plan you already have. Click "Connect", enter the device code in the OpenAI page, choose your model, and you're set.
189
190	This is the first step toward account-backed LLM plans in Agent Zero. More integrations are coming, including Gemini CLI and Claude Code through extra-usage.
191
192	## A0 CLI Connector: Extend Onto Your Host Machine
193
194	<img alt="A0 CLI driving the host browser through a Google Cloud VM creation flow" src="docs/res/usage/a0-cli/host-browser.gif" />
195	<br>
196
197	The A0 CLI Connector is not a separate CLI agent. It connects to a running Agent Zero instance and gives that instance a terminal-native bridge to your host machine - so the same agent (with all its memory, projects, and skills) can also work on real files outside the Docker container.
198
199	Install the connector on the machine you want Agent Zero to work on, not inside the Agent Zero container.
200
201	### macOS / Linux
202
203	```bash
204	curl -LsSf https://cli.agent-zero.ai/install.sh \| sh
205	```
206
207	### Windows PowerShell
208
209	```powershell
210	irm https://cli.agent-zero.ai/install.ps1 \| iex
211	```
212
213	Then run `a0` to connect your terminal to an existing Agent Zero instance. It can usually discover a local instance automatically, or you can point it at a remote URL hosted somewhere else, such as a VPS or tunnel.
214
215	This is especially useful if you:
216
217	- prefer CLI workflows;
218	- want Agent Zero to work in an existing local repository;
219	- are running Agent Zero on a remote server;
220	- want Docker isolation for Agent Zero while still granting explicit, controlled access to host-side work.
221
222	For full setup, see the [A0 CLI Connector guide](https://www.agent-zero.ai/p/docs/a0-cli-connector/) (or the [in-repo guide](./docs/guides/a0-cli-connector.md)).
223
224	## Projects, Skills, Agent Profiles, and Model Presets
225
226	Projects isolate workspaces, instructions, memory, secrets, knowledge, repositories, and model-preset choices. Clone a public or private Git repo into a project and give the agent context that belongs to that work alone.
227
228	Skills can be loaded on demand by Agent Zero, or pinned from the chat input when you want a specific procedure to stay active.
229
230	Agent Profiles change the broader working style of the current chat.
231
232	Model Presets are named shortcuts for model setups, so you can quickly switch between fast, balanced, cheap, local, or high-power model choices.
233
234	## Multi-Agent Cooperation
235
236	Every agent can create subordinate agents to break down work. The superior gives tasks and receives reports; subagents keep their own contexts focused and return their findings when done.
237
238	This makes Agent Zero useful for research, software engineering, data analysis, plugin development, and tasks where several specialized perspectives are better than one overloaded context.
239
240	## Transparent and Extensible by Design
241
242	Almost nothing is hidden. Prompts live in `prompts/`, tools live in `tools/` or plugins, and built-in behavior can be inspected, changed, replaced, or extended.
243
244	Agent Zero supports plugins, MCP, A2A, custom tools, custom prompts, project-scoped configuration, environment-based deployment settings, and a Web UI designed to keep the agent's work readable in real time.
245
246	## Time Travel
247
248	Time Travel gives Agent Zero-owned `/a0/usr` workspaces snapshot history, diff inspection, travel, and revert. It is designed for recoverable agent work: see what changed, compare files, inspect a past state, and roll back when needed.
249
250	<img alt="Time Travel" src="docs/res/time-travel.png" />
251
252	It is not a replacement for Git or backups. It is a practical safety layer for the workspace where agents are actively creating and editing files.
253
254	## Real-World Use Cases
255
256	- Software engineering: inspect a codebase, make scoped edits, run tests, explain tradeoffs, and keep a recoverable history of file changes.
257	- Host-machine development: connect with `a0` and let Agent Zero work in your real local repositories, or clone them through Git Projects feature in the Web UI.
258	- Design inspiration and UI iteration: browse the web, annotate elements you like, and pull components into your own stack.
259	- Financial analysis and charting: collect data, correlate events, create spreadsheets, and generate editable charts.
260	- Office deliverables: cowork on documents, spreadsheets, and presentation decks instead of trapping the result in chat text.
261	- Web and mobile QA: browse an app, annotate UI issues, install browser extensions, and turn visual comments into actionable fixes.
262	- API integration: paste an API snippet, let the agent build a working example, and store the pattern for future use.
263	- Client/project isolation: keep memory, secrets, instructions, files, and model choices separated by project.
264	- Scheduled operations: run recurring checks and monitoring tasks with project-scoped context and credentials.
265
266	## Documentation
267
268	\| I want to... \| Start here \|
269	\| --- \| --- \|
270	\| Install or update Agent Zero \| [Installation](./docs/setup/installation.md) \|
271	\| Learn the UI and basic workflow \| [Quickstart](./docs/quickstart.md) \|
272	\| Browse, annotate, and use Browser screenshots \| [Browser guide](./docs/guides/browser.md) \|
273	\| Use the Linux desktop and LibreOffice \| [Desktop guide](./docs/guides/desktop.md) \|
274	\| Connect Agent Zero to host-machine files and shell \| [A0 CLI Connector](https://www.agent-zero.ai/p/docs/a0-cli-connector/) \|
275	\| Use projects and Git workspaces \| [Projects guide](./docs/guides/projects.md) \|
276	\| Create a small plugin \| [Create a Small Plugin](./docs/guides/create-plugin.md) \|
277	\| Add or remove active skills \| [Skills guide](./docs/guides/skills.md) \|
278	\| Create or switch Agent Profiles \| [Agent Profiles](./docs/guides/agent-profiles.md) \|
279	\| Create or switch Model Presets \| [Model Presets](./docs/guides/model-presets.md) \|
280	\| Manage and curate memories \| [Memory guide](./docs/guides/memory.md) \|
281	\| Learn the everyday chat controls \| [Usage guide](./docs/guides/usage.md) \|
282	\| Configure MCP or external tools \| [MCP setup](./docs/guides/mcp-setup.md) \|
283	\| Understand the architecture and internals \| [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero) \|
284	\| Build an advanced extension \| [Extensions](./docs/developer/extensions.md) \|
285	\| Contribute to the project \| [Contributing](./docs/guides/contribution.md) \|
286	\| Troubleshoot problems \| [Troubleshooting](./docs/guides/troubleshooting.md) \|
287
288	## Build With Us
289
290	Agent Zero is built for people who want to understand and shape their tools.
291
292	You can help by improving docs, creating skills, publishing plugins, testing model/provider setups, reporting bugs, sharing workflows, or contributing core improvements. Start with the [Contributing guide](./docs/guides/contribution.md), browse the [Plugin Hub](https://www.agent-zero.ai/p/docs/plugins/#plugin-hub), or bring ideas to Discord.
293
294	## Community and Support
295
296	- [Discord](https://discord.gg/B8KZKNsPpj) for live discussion and help.
297	- [Skool Community](https://www.skool.com/agent-zero) for community learning.
298	- [YouTube](https://www.youtube.com/@AgentZeroFW) for demos and tutorials.
299	- [X](https://x.com/Agent0ai), [LinkedIn](https://www.linkedin.com/company/109758317), and [Warpcast](https://warpcast.com/agent-zero) for updates.
300	- [GitHub Issues](https://github.com/agent0ai/agent-zero/issues) for bugs and feature requests.
301
302	[Space Agent](https://github.com/agent0ai/space-agent) is the related, more polished product direction for the agent-shaped workspace. Agent Zero remains the open framework and Linux-powered workbench.
303
304	## Safety Model
305
306	Agent Zero is powerful because it can use a real environment.
307
308	- Keep it running inside Docker or another isolated environment.
309	- Do not mount your entire home directory unless you understand the risk.
310	- Grant A0 CLI Read+Write access and remote code execution only for machines and workspaces you trust.
311	- Store credentials in project secrets or settings, not in prompts or public files.
312	- Review actions that touch accounts, money, production systems, or private data.
313	- Keep backups for important workspaces.