| 1 | # A0 CLI Connector |
| 2 | |
| 3 | A0 CLI connects your terminal to Agent Zero. |
| 4 | |
| 5 | It is not a second agent. Agent Zero is still the one thinking, remembering, and |
| 6 | using tools. A0 CLI is the doorway that lets Agent Zero work on the computer |
| 7 | where the CLI is running. |
| 8 | |
| 9 | Agent Zero lives in Docker because that is safer and easier to manage. A0 CLI is |
| 10 | the intentional bridge for moments when you want Agent Zero to work with your |
| 11 | real files, terminal, or browser on the host machine. |
| 12 | |
| 13 | Agent Zero stays in Docker. A0 CLI installs on the host machine. |
| 14 | |
| 15 | The same connector can also let Agent Zero use a Chrome-family browser on your |
| 16 | computer. |
| 17 | |
| 18 | ## Quick Install |
| 19 | |
| 20 | **macOS / Linux:** |
| 21 | ```bash |
| 22 | curl -LsSf https://cli.agent-zero.ai/install.sh | sh |
| 23 | ``` |
| 24 | |
| 25 | **Windows (PowerShell):** |
| 26 | ```powershell |
| 27 | irm https://cli.agent-zero.ai/install.ps1 | iex |
| 28 | ``` |
| 29 | |
| 30 | Run these on the host machine, not inside the Agent Zero container. |
| 31 | |
| 32 | The installer handles the small Python helper it needs. |
| 33 | |
| 34 | ## Open it and start working |
| 35 | |
| 36 | 1. Make sure Agent Zero is already running. |
| 37 | 2. Launch A0 CLI on the host machine: |
| 38 | |
| 39 | ```bash |
| 40 | a0 |
| 41 | ``` |
| 42 | |
| 43 | 3. If Agent Zero is running on the same machine, A0 CLI will usually find it. |
| 44 | 4. If Agent Zero is somewhere else, enter its web address. |
| 45 | 5. Open or create a chat and confirm you can talk to Agent Zero from the host machine. |
| 46 | |
| 47 | > [!NOTE] |
| 48 | > If A0 CLI says connector support is missing, update Agent Zero first. |
| 49 | |
| 50 | ### Connection picker |
| 51 | |
| 52 | On launch, A0 CLI opens a host picker. If it finds Agent Zero on this machine, |
| 53 | click **Connect**. If Agent Zero is somewhere else, click **Enter URL manually** |
| 54 | and paste the address. |
| 55 | |
| 56 |  |
| 57 | |
| 58 | Useful launch options: |
| 59 | |
| 60 | ```bash |
| 61 | a0 --host http://localhost:32080 |
| 62 | a0 --no-auto-connect |
| 63 | a0 --no-docker-discovery |
| 64 | ``` |
| 65 | |
| 66 | You can also set the address before launching: |
| 67 | |
| 68 | ```bash |
| 69 | export AGENT_ZERO_HOST=http://localhost:32080 |
| 70 | a0 |
| 71 | ``` |
| 72 | |
| 73 | If **Remember this host** is enabled, the CLI saves that address for next time. |
| 74 | |
| 75 | ### The connected shell |
| 76 | |
| 77 | After connecting, the shell shows the Agent Zero address, current project, model, |
| 78 | local folder, Agent Zero workspace, and the message box. |
| 79 | |
| 80 |  |
| 81 | |
| 82 | Use the footer when your terminal supports function keys: |
| 83 | |
| 84 | | Key | Action | |
| 85 | |---|---| |
| 86 | | `F3` | Toggle host file read/write access for the active CLI session. | |
| 87 | | `F4` | Toggle remote code execution through the active CLI session. | |
| 88 | | `F5` | Clear the visible chat log. | |
| 89 | | `F6` | Open the chat list. | |
| 90 | | `F7` | Nudge the active agent run. | |
| 91 | | `F8` | Pause the active agent run. | |
| 92 | | `Ctrl+C` | Exit. | |
| 93 | | `Ctrl+P` | Open the command palette. | |
| 94 | |
| 95 | `Ctrl+P` is the best fallback when an IDE terminal or SSH client captures |
| 96 | function keys. |
| 97 | |
| 98 |  |
| 99 | |
| 100 | ### Slash commands |
| 101 | |
| 102 | Type a slash command in the message box and press Enter. Most commands are also |
| 103 | available from `Ctrl+P`. |
| 104 | |
| 105 | | Command | Use it for | |
| 106 | |---|---| |
| 107 | | `/new` | Create a new empty chat. | |
| 108 | | `/chats` | List previous chats. Add `--project`, `--all-projects`, or `--sort=updated|created|name` when needed. | |
| 109 | | `/project` | Open the project menu, or switch directly with `/project <name>`. | |
| 110 | | `/profile` | Open the profile menu; add a name to select, or a quoted name and instructions to create. | |
| 111 | | `/permissions` | Edit Tool, MCP, and Skill access for the current profile. | |
| 112 | | `/compact` | Compact the current chat after confirmation. | |
| 113 | | `/pause` | Pause the active run. | |
| 114 | | `/resume` | Resume a paused run. | |
| 115 | | `/nudge` | Nudge the active run. | |
| 116 | | `/presets` | Choose a model preset. | |
| 117 | | `/models` | Edit the active models. | |
| 118 | | `/browser` | Check or change Browser mode. | |
| 119 | | `/attach` | Attach local image files to the next message. Aliases: `/image`, `/img`. | |
| 120 | | `/keys` | Show or hide key and widget help. | |
| 121 | | `/disconnect` | Disconnect and return to the host connection flow. | |
| 122 | | `/help` | Print the available command list in the shell. | |
| 123 | | `/quit` | Disconnect and exit the CLI. | |
| 124 | |
| 125 | ### Agent profiles and permissions |
| 126 | |
| 127 | Open the compact profile menu: |
| 128 | |
| 129 | ```text |
| 130 | /profile |
| 131 | ``` |
| 132 | |
| 133 |  |
| 134 | |
| 135 | Select an existing profile by its unquoted name or ID, or create one directly: |
| 136 | |
| 137 | ```text |
| 138 | /profile Developer |
| 139 | /profile "Source Scout" "Verify every important claim and cite the source." |
| 140 | ``` |
| 141 | |
| 142 | Quick creation opens a fresh chat with the new profile selected. |
| 143 | |
| 144 |  |
| 145 | |
| 146 | Use `/permissions` to edit the current profile's Tools, MCPs, and Skills. |
| 147 | Entries move through **Default**, **On**, and **Off**; the Tools, MCPs, and |
| 148 | Skills tabs each expose their own category default. |
| 149 | |
| 150 |  |
| 151 | |
| 152 | Profile editing follows the current chat scope. A project chat writes project |
| 153 | overrides; a chat with no project writes Global overrides. For the complete Web |
| 154 | UI and file-format guide, see [Agent Profiles](agent-profiles.md). |
| 155 | |
| 156 | ## Host Browser |
| 157 | |
| 158 | Use this when you want Agent Zero to browse with a browser on your computer. |
| 159 | This is useful when the page, login, or browser profile should stay on your |
| 160 | machine. |
| 161 | |
| 162 | ### Setup Checklist |
| 163 | |
| 164 | - [ ] Keep A0 CLI connected to the Agent Zero chat. |
| 165 | - [ ] In Agent Zero Web UI, open Browser plugin settings and choose **Bring Your |
| 166 | Own Browser**. |
| 167 | - [ ] If you want Agent Zero to use an already-open personal browser window, |
| 168 | open that browser first. |
| 169 | - [ ] In that browser, open its remote debugging page. |
| 170 | - [ ] Enable **Allow remote debugging for this browser instance**. |
| 171 | |
| 172 | Remote debugging pages: |
| 173 | |
| 174 | | Browser | Page | |
| 175 | | --- | --- | |
| 176 | | Chrome, Edge, Brave, Vivaldi, Chromium | `chrome://inspect/#remote-debugging` | |
| 177 | | Opera | `opera://inspect/#remote-debugging` | |
| 178 | |
| 179 |  |
| 180 | |
| 181 | When Agent Zero performs its first Browser action against that host browser, |
| 182 | the browser asks for confirmation. Click **Allow** if you trust this Agent Zero |
| 183 | instance and A0 CLI connection. |
| 184 | |
| 185 |  |
| 186 | |
| 187 | A0 CLI does not take over the browser while it is only checking status. Browser |
| 188 | control starts when Agent Zero actually needs to use the browser. |
| 189 | |
| 190 | > [!IMPORTANT] |
| 191 | > Remote debugging gives the connected app full control of that browser session, |
| 192 | > including access to saved data, cookies, site data, and navigation. Use it only |
| 193 | > with trusted Agent Zero instances and browser windows you intend the agent to |
| 194 | > control. |
| 195 | |
| 196 | The **Host browser** list in Browser settings comes from the connected local A0 |
| 197 | CLI, not from the Agent Zero Web UI server. It shows Automatic, currently |
| 198 | advertised debug endpoints, and **Custom endpoint**. If a newly authorized |
| 199 | browser does not appear, restart or reconnect A0 CLI. |
| 200 | |
| 201 | If the inspect checkbox is not enough for your browser build, launch it with an |
| 202 | explicit remote debugging port and a separate profile: |
| 203 | |
| 204 | ```bash |
| 205 | opera --remote-debugging-port=9222 --user-data-dir="$HOME/.config/a0-opera-debug" |
| 206 | ``` |
| 207 | |
| 208 | Then choose **Custom endpoint** in Browser settings, run |
| 209 | `/browser localhost:9222` in A0 CLI, or pass the discovery address to A0 CLI. A |
| 210 | full DevTools WebSocket endpoint also works: |
| 211 | |
| 212 | ```bash |
| 213 | export A0_HOST_BROWSER_REMOTE_DEBUGGING_ENDPOINTS="http://localhost:9222" |
| 214 | ``` |
| 215 | |
| 216 | ### Browser Profiles |
| 217 | |
| 218 | ```bash |
| 219 | /browser profile |
| 220 | /browser profile chrome Default |
| 221 | /browser profile chrome-a0 Default |
| 222 | ``` |
| 223 | |
| 224 | If your everyday Chrome window cannot be used, choose the separate A0 browser |
| 225 | profile instead. It keeps its own cookies and sign-ins, so you may need to log in |
| 226 | there once. |
| 227 | |
| 228 | ### Choose Browser Mode |
| 229 | |
| 230 | In Agent Zero Web UI, open Browser plugin settings and choose one of: |
| 231 | |
| 232 | - **Docker browser:** use Agent Zero's built-in Docker browser. |
| 233 | - **Bring Your Own Browser:** use the browser on your computer through A0 CLI. |
| 234 | If A0 CLI is not connected, Agent Zero will tell you instead of quietly using |
| 235 | a different browser. |
| 236 | |
| 237 | You can also find the Browser commands from the CLI command palette: |
| 238 | |
| 239 |  |
| 240 | |
| 241 | When **Bring Your Own Browser** is selected, the first browsing request asks A0 |
| 242 | CLI to prepare the browser automatically. These commands are useful when you |
| 243 | want to check or change the state yourself: |
| 244 | |
| 245 | ```bash |
| 246 | /browser status |
| 247 | /browser host on |
| 248 | /browser relaunch |
| 249 | ``` |
| 250 | |
| 251 | `/browser status` shows which Browser mode is selected and whether your browser |
| 252 | is ready: |
| 253 | |
| 254 |  |
| 255 | |
| 256 | `/browser host` switches the active chat to Bring Your Own Browser mode: |
| 257 | |
| 258 |  |
| 259 | |
| 260 | Run `/browser container` to switch that chat back to Docker browser mode. |
| 261 | |
| 262 | `/browser privacy` reminds users where the Browser content policy lives: |
| 263 | |
| 264 |  |
| 265 | |
| 266 | If the selected browser profile is already open in another window, close that |
| 267 | window and try again. You can also run `/browser relaunch`. |
| 268 | |
| 269 | You do not need to install Chrome DevTools MCP for this. A0 CLI already includes |
| 270 | what it needs to connect to the browser you approve. |
| 271 | |
| 272 | ### Page Privacy |
| 273 | |
| 274 | Browser settings decide what Agent Zero may do with page text and screenshots |
| 275 | from your own browser: |
| 276 | |
| 277 | - **Local models only:** use host-browser page content only with local models. |
| 278 | - **Warn when using cloud:** allow cloud models, but show a warning. |
| 279 | - **Allow:** allow without warning. |
| 280 | |
| 281 | > [!NOTE] |
| 282 | > The live Browser surface shows the Docker browser. When Agent Zero uses your |
| 283 | > host browser, results and screenshots appear in the chat, but the live Canvas |
| 284 | > is not a stream of your personal browser window. |
| 285 | |
| 286 | ## Give this to another agent |
| 287 | |
| 288 | If another agent is helping with setup, do not paste a whole checklist. Paste one line: |
| 289 | |
| 290 | ```text |
| 291 | Set up the A0 CLI connector for Agent Zero on this machine using the setup-a0-cli Skill. |
| 292 | ``` |
| 293 | |
| 294 | ## Troubleshooting |
| 295 | |
| 296 | - **Nothing appears locally:** Enter the Agent Zero web address manually or export `AGENT_ZERO_HOST`. |
| 297 | - **You tried to install from inside Docker:** A0 CLI belongs on the host machine. Agent Zero stays in Docker. |
| 298 | - **Function keys do nothing:** Some terminals and IDEs capture function keys. Use `Ctrl+P`. |
| 299 | - **A0 CLI says connector support is missing:** Update Agent Zero. |
| 300 | - **Host browser says repair is needed:** Run `/browser repair`. |
| 301 | - **Host browser waits for relaunch:** Close the selected Chrome, Edge, or Chromium profile and run `/browser relaunch`. |
| 302 | |
| 303 | ## Related links |
| 304 | |
| 305 | - [Quick Start](../quickstart.md) |
| 306 | - [Installation Guide](../setup/installation.md) |
| 307 | - [Browser Guide](browser.md) |
| 308 | - [MCP Setup](mcp-setup.md) |