Walk new users from their first message through the Cloud provider grid, filtered Plugin Hub, OpenCode Go installation, browser refresh and model selection. Link the guide from the README, docs index, Onboarding and Usage, and add seven optimized screenshots of the real setup flow. Use the verified Go model IDs glm-5.3 and glm-5.3-flash, explain the free-model restriction, and distinguish checked setup from untested model responses. Validation: real installation and model selection on the dedicated instance; local links, anchors, image dimensions, privacy and whitespace checked. No subscription credentials were entered or paid inference performed.
18 KiB
Usage Guide
This guide is the practical tour of Agent Zero after installation. It explains what you can do in the Web UI, what to try first, and where to go when you want the deeper source-linked explanation.
For architecture, backend flow, Web UI internals, plugin lifecycle, and API details, use DeepWiki for Agent Zero.
Basic Operations
Agent Zero is built around a chat, a working Linux environment, and a Web UI that lets you watch and steer the work.
Common places to start:
- New Chat: start a clean conversation.
- Projects: give a chat its own workspace, files, memory, secrets, and instructions.
- Memory: review what Agent Zero has learned or imported.
- Tasks: create scheduled, planned, or manual automations.
- Files: open the Agent Zero file browser.
- Settings: configure models, credentials, preferences, plugins, and backup.
- Browser: open the live Browser surface when you want to watch browsing or annotate a page.
- Desktop: open the live Linux desktop when you want GUI apps, a terminal window, or LibreOffice Cowork.
Type directly into the welcome message box to start a new chat. If models need setup, the chat holds your message while you complete onboarding, then retries it once the model is configured.
Use Restart from the sidebar when you need the framework to reload after settings or code changes.
Find a chat or message
Use Search below Chats to enter a chat title or a phrase you remember. Matching message excerpts appear under the chat name. Click a result to open the conversation. Your project, status, and activity filters still apply.
Clear the query with the close button or Escape. If you do not see the field, open Sidebar view options → Search → Standard. Compact puts search behind a magnifier; No search hides it. Search covers the current chat list, not deleted or archived chats, and is separate from the Welcome Chats search.
For conversations from another app, see Move your chats into Agent Zero.
Customize Welcome
Drag a section's handle to move it, or click the handle for Move up and Move down. With the handle focused, arrow keys move the section; Home and End move it to the beginning or end.
Use a section's close button to hide it. Show all dismissed at the bottom restores hidden sections, notices, and discovery cards, including the greeting and message box. It restores visibility without resetting your order. These layout choices are saved in this browser.
The puzzle button beside the restore control opens Plugin Hub with welcome plugins selected. Additional panels depend on which plugins you have installed.
While Agent Zero is working
Expand a tool row to inspect its details. Use the controls around the message box to steer the current chat:
| Control | What it does |
|---|---|
| Pause Agent / Resume Agent | Pause processing and continue it later. |
| Stop agent (square send button) | Stop the current run. It appears while the agent is running and the message box is empty. |
| Add to queue | Add a follow-up while a run is active. Queued messages remain visible above the composer. |
| Send now / Send all | Send one queued message immediately, or combine and send the queue. Remove an item to cancel that queued message. |
| Nudge | Prompt the agent to continue when it needs another push. |
| Compact | Summarize a long conversation to reduce the context it uses. |
| + → History / Context | Inspect the conversation history or the current model context. |
When a result includes a file link, open it to inspect the artifact. Use a message's Branch chat action to try a different direction from that point; the original chat stays unchanged.
Set a goal for longer work
Use + → Goal mode to prefill /goal , then write a concrete objective and
send it. For example:
/goal Prepare the kickoff plan and a short review checklist
An active goal keeps the agent working through intermediate updates until it marks the goal complete or blocked. The goal strip lets you edit, pause, resume, or delete the goal. Pausing a goal is separate from Pause Agent; use the latter when you need to pause the chat's processing too.
Goals belong to the current chat. Use Tasks and Scheduling when the work should run later or on a schedule.
Plugins And Plugin Hub
Plugins add integrations, tools, panels, and automation helpers.
Open Plugins from the dashboard or sidebar to see what is installed.
Use the Browse tab or Install button to open the Plugin Hub.
Looking for a model provider? Choose the Provider filter. The OpenCode Go guide shows how to find a provider that is missing from onboarding, install its plugin, and configure the models.
Before installing a plugin, read its description, README, permissions, and source link. Treat plugins like any other code you run in your workspace: install the ones you trust and remove what you do not use.
When you want to make your own first plugin, start with something small and
visible. The Create a Small Plugin guide walks through a
local Web UI plugin that adds an unread dot to the chat list and then reviews it
with the review reference in a0-create-plugin.
Skills, Agent Profiles, And Model Presets
The small controls around the chat input let you shape the current conversation without opening the full Settings screen.
Skills
Skills are focused instructions Agent Zero can load when it needs them. You can also pin a skill manually for the current chat.
Click the + button in the chat input, then click Skills.
Use the selector to add or remove active skills.
Active skills are added to the Protocol part of the prompt, so keep the list short and intentional. See the Skills guide.
Agent Profiles
Agent Profiles give the selected chat a role, instructions, model preset, and Tool, MCP, and Skill access policy.
Use the profile menu near the chat input to switch the current chat or edit a profile. Select Manage agents to create, duplicate, reset, delete, or change profile availability for Global or one project.
Use Settings → Agent → Agent Config when you want to change the default profile for new Global chats.
See the Agent Profiles guide.
Model Presets
Model Presets are named shortcuts for model choices. Use them for setups like
Best, Balanced, Fast Cheap, or a model name you can spot quickly.
Click Edit Presets when you want to add or rename presets.
See the Model Presets guide.
File Attachments
Attach files when the agent should read, summarize, transform, or organize them.
You can attach one file or several files, then describe what should happen:
Read these PDFs and create a short comparison table.
Move these files into a clean folder structure and explain what changed.
Attached files are visible in the chat input before you send the message, so you can remove mistakes before Agent Zero starts working.
Tool Usage
You usually do not need to name tools. Say what you want done and Agent Zero will choose whether it needs the browser, code execution, files, knowledge, plugins, or another available capability.
Good prompts are specific about the desired result:
Research three deployment options for this app. Cite sources and finish with a recommendation.
Open the attached CSV, find the main trend, and create a chart I can edit later.
Inspect this repository and propose the safest first improvement before changing files.
When you do want internals, use DeepWiki for Agent Zero.
Browser Tool And Surface
The Browser has two parts:
- the
browsertool, which the agent can call directly; - the visible Browser surface in the Canvas, where you can watch and annotate pages.
Ask naturally:
Use the Browser tool to compare these pages and take screenshots of the important parts.
Open my local app in the Browser. I will annotate the page, then you can fix the issues.
For screenshots, history, annotations, Docker browser mode, host-browser mode through A0 CLI, privacy controls, and Chrome extensions, see the Browser Guide.
External browser MCP tools are still useful for specialized setups. See MCP Setup.
Desktop Surface
The Desktop surface opens Agent Zero's own Linux desktop in the Canvas. Use it when you want the agent to work visually with GUI apps, open a terminal, or cowork with you in LibreOffice.
The New menu can create Markdown, Writer, Spreadsheet, and Presentation files. Writer, Calc, and Impress run inside the Desktop, so you can edit by hand while Agent Zero creates, updates, saves, and verifies the same files.
For the screenshot walkthrough and prompt examples, see the Desktop Guide.
Agent-To-Agent Communication
Agent Zero instances can communicate through A2A when you want multiple instances to collaborate.
Use A2A when you have a clear reason to split work across Agent Zero instances, such as a specialist server, a remote machine, or a project-specific agent. See A2A Setup.
Multi-Agent Cooperation
Inside a single Agent Zero instance, the main agent can create subordinate agents to investigate focused parts of a larger job.
This is useful for research, code review, comparison work, and tasks where one agent should gather information while another keeps the main plan moving.
Projects
Projects tell Agent Zero what world it is working in. Use one when a chat needs its own files, instructions, memory, secrets, or model settings.
The simple flow:
- Open Projects from the dashboard.
- Click Create project.
- Give it a clear title.
- Add a short description.
- Write practical instructions.
- Save it.
- Open a chat and choose the project from the top-right project picker.
Good project instructions tell Agent Zero what should be different in that workspace:
When this project is active:
- Explain steps in plain language before technical detail.
- Prefer screenshots, checklists, and concrete examples.
- Keep generated files inside this project unless I ask otherwise.
- Ask before using credentials, private data, or external accounts.
Use projects for client work, code repositories, research topics, recurring reports, and any workflow where context matters.
See the Projects guide for the full screenshot walkthrough.
Tasks And Scheduling
Tasks let Agent Zero run work later, repeatedly, or on demand.
Use tasks for:
- morning or weekly reports;
- monitoring a source and summarizing changes;
- recurring cleanup or export jobs;
- project-specific checks;
- manual batch jobs you want to run again.
Open Tasks from the dashboard or sidebar.
When creating a task, focus on four things:
- Name: what you will recognize later.
- Type: scheduled, planned, or ad-hoc.
- Project: optional, but recommended when the task needs specific context or secrets.
- Prompt: the actual work Agent Zero should perform.
Example:
Name: Weekly docs review
Type: Scheduled
Project: Documentation
Prompt: Check the docs project for stale screenshots, broken links, and confusing sections. Summarize what needs attention.
Project-scoped tasks inherit project instructions, variables, secrets, files, and memory. That means you can improve task behavior later by improving the project instead of repeating every rule in every task.
Secrets And Variables
Use Secrets for sensitive values such as API keys, tokens, passwords, and credentials.
Use Variables for non-sensitive settings such as regions, URLs, usernames, formats, or feature flags.
Refer to them by name in chat:
Use the project GITHUB_TOKEN to check repository status.
Do not paste credentials into chat messages or public files. Keep your own copy of important secrets because backups may not include every secret.
Remote Access Via Tunneling
Tunnels let you reach your local Agent Zero instance from another device or share it temporarily.
Before creating a tunnel:
- set UI authentication;
- understand that anyone with the tunnel URL can try to open your instance;
- stop the tunnel when you no longer need it.
Open Settings -> External Services -> Flare Tunnel to create or stop a tunnel.
Voice Interface
Agent Zero supports text-to-speech and speech-to-text through built-in voice plugins:
_kokoro_ttsprovides container-side Kokoro speech synthesis when enabled._whisper_sttprovides local Whisper transcription and adds the microphone control when enabled.- Browser-native
speechSynthesisremains the fallback output path when_kokoro_ttsis disabled.
Use the Voice section in Agent settings or the plugin settings in Agent Plugins to configure providers. Use the sidebar Speech preference when you want Agent Zero to read responses automatically.
Use speech when you want to listen while doing something else, dictate a prompt, or make the interface more accessible.
Speech-to-text settings live in the Whisper STT plugin card and include model size, language code, voice message handling, silence threshold, and recording behavior. The microphone button appears in the chat input when _whisper_stt is enabled.
Important
Whisper STT and Kokoro TTS operate locally within the Docker/container runtime when their plugins are enabled. Browser fallback TTS runs locally in the browser. No voice path requires OpenAI APIs.
Mathematical Expressions
Agent Zero can render mathematical notation with KaTeX.
Ask for the format you want:
Solve this step by step and show the final equations in KaTeX.
File Browser
The File Browser lets you inspect and manage files inside the Agent Zero environment.
Use it to:
- upload files;
- download generated work;
- create folders;
- rename or delete files;
- open editable text files;
- inspect the project or
/a0/usrworkspace.
For file-based work, prefer /a0/usr or a project workspace. Avoid storing
important work only in temporary directories.
Memory Management
Memory is where Agent Zero keeps useful remembered information from conversations and imported knowledge. It is powerful, but it is not magic. Long-term AI memory still needs curation; this is not fully solved even by the largest AI labs and companies.
Open Memory when you want to search, review, edit, copy, or remove stored entries.
The controls let you choose a memory directory, filter by area, set a result limit, search, adjust match threshold, and clear filtered results.
Use memory deliberately:
- keep durable facts and useful patterns;
- remove old test data;
- edit memories that became inaccurate;
- use project memory for project-specific context;
- create a backup before large cleanup.
If Agent Zero does something unexpected, repeats a wrong behavior, or seems to remember the wrong thing, Memory is one of the first places to look. A stale or incorrect memory can poison the processing instead of helping it.
Click a memory row to inspect its full content and metadata. From the detail view you can copy, edit, or delete the entry.
For a practical cleanup checklist, see the Memory Guide.
Backup And Restore
Backups protect your chats, projects, knowledge, memory, settings, skills, and workspace files.
Create a backup before:
- major updates;
- plugin experiments;
- bulk memory cleanup;
- moving to a new machine;
- deleting or reorganizing important project files.
Open Settings -> Backup & Restore to create or restore a backup.
Secrets are sensitive and may not always be included in backup archives. Keep a separate secure copy of credentials you depend on.




























