| 1 | # Agent Zero Launcher |
| 2 | |
| 3 | Agent Zero Launcher is the desktop app for installing, running, switching, and |
| 4 | opening Dockerized Agent Zero Instances without starting from Docker commands. |
| 5 | |
| 6 | Use it when you are setting up a new machine, when you want a quiet inventory of |
| 7 | installed Agent Zero images, or when you want one place to open local and remote |
| 8 | Instances. |
| 9 | |
| 10 | ## Start Fresh On A New Machine |
| 11 | |
| 12 | 1. Download Agent Zero Launcher from the |
| 13 | [A0 Launcher releases](https://github.com/agent0ai/a0-launcher/releases). |
| 14 | 2. Open the app. |
| 15 | 3. If the launcher cannot reach Docker yet, follow the setup dialog. |
| 16 | 4. If Agent Zero is already hosted on another computer or VPS, click |
| 17 | **Add remote Instance** instead of setting up local Docker. |
| 18 | |
| 19 |  |
| 20 | |
| 21 | The first setup dialog keeps the choice simple: |
| 22 | |
| 23 | - **Continue** starts the local runtime setup or refreshes the runtime state. |
| 24 | - **Refresh** checks again after you start Docker yourself. |
| 25 | - **Add remote Instance** saves an existing Agent Zero URL and lets you use the |
| 26 | Launcher without local Docker. |
| 27 | |
| 28 | ## Installs |
| 29 | |
| 30 | When Docker is ready, Launcher opens to **Installs**. This page shows official |
| 31 | Agent Zero release lines and local images. |
| 32 | |
| 33 |  |
| 34 | |
| 35 | Cards usually mean: |
| 36 | |
| 37 | - **latest** tracks the newest published Agent Zero release image. |
| 38 | - **ready** tracks the development-ready image when you intentionally work from |
| 39 | that branch. |
| 40 | - Version cards such as **1.20**, **1.19**, or **1.18** are pinned release |
| 41 | images. |
| 42 | - **Install** downloads an image. |
| 43 | - **Run** starts an installed image as a local Instance. |
| 44 | |
| 45 | ## Instances |
| 46 | |
| 47 | Open **Instances** after you run Agent Zero. This is where local containers and |
| 48 | saved remote Instances live. |
| 49 | |
| 50 | Use the Instance card to: |
| 51 | |
| 52 | - open the Web UI; |
| 53 | - start, stop, rename, or delete the container; |
| 54 | - open logs; |
| 55 | - use **Backup `/a0/usr`** to download the same user-data backup you can create |
| 56 | from Agent Zero Core; |
| 57 | - use **Restore `/a0/usr`** to restore that backup zip into the selected |
| 58 | Instance; |
| 59 | - open A0 CLI when the host connector is installed. |
| 60 | |
| 61 | Launcher keeps local Instances and remote Instances separate, so deleting a |
| 62 | container is not the same as deleting a saved remote URL or a workspace backup. |
| 63 | |
| 64 | ## Updating With Launcher |
| 65 | |
| 66 | For same-major Agent Zero updates, the Web UI **Self Update** is still the |
| 67 | normal path. |
| 68 | |
| 69 | For a major image jump such as v1.20 -> v2.0, use Launcher or Docker to start a |
| 70 | new v2.0 Instance, then restore a backup from the old Instance. In Launcher, the |
| 71 | flow is: **Instances -> Backup `/a0/usr`** on the old v1.20 Instance, **Installs |
| 72 | -> latest -> Install/Run**, then **Instances -> Restore `/a0/usr`** on the new |
| 73 | v2.0 Instance. This avoids mixing an old root install with a new Docker image. |
| 74 | |
| 75 | See [Updating from v1.20 to v2.0](../setup/installation.md#updating-from-v120-to-v20). |
| 76 | |
| 77 | ## Capture Launcher Screenshots With Playwright |
| 78 | |
| 79 | Launcher is an Electron app, so browser-only Playwright commands are not enough. |
| 80 | Use Playwright's Electron bridge and the local Electron binary from the Launcher |
| 81 | repo. |
| 82 | |
| 83 | The pattern below installs Playwright into a temporary folder outside the repo, |
| 84 | launches local Launcher content, waits for the `a0app://content/` window, and |
| 85 | saves a screenshot. |
| 86 | |
| 87 | ```bash |
| 88 | mkdir -p /tmp/a0-launcher-playwright |
| 89 | npm install --prefix /tmp/a0-launcher-playwright playwright |
| 90 | ``` |
| 91 | |
| 92 | ```bash |
| 93 | NODE_PATH=/tmp/a0-launcher-playwright/node_modules node <<'JS' |
| 94 | const { _electron: electron } = require("playwright"); |
| 95 | |
| 96 | const launcher = "/home/eclypso/a0/a0-launcher"; |
| 97 | const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); |
| 98 | |
| 99 | (async () => { |
| 100 | const app = await electron.launch({ |
| 101 | executablePath: `${launcher}/node_modules/electron/dist/electron`, |
| 102 | args: [launcher], |
| 103 | env: { |
| 104 | ...process.env, |
| 105 | A0_LAUNCHER_LOCAL_REPO: launcher, |
| 106 | ELECTRON_DISABLE_SECURITY_WARNINGS: "true", |
| 107 | }, |
| 108 | }); |
| 109 | |
| 110 | const windows = []; |
| 111 | app.on("window", (page) => windows.push(page)); |
| 112 | windows.push(await app.firstWindow()); |
| 113 | |
| 114 | let page = null; |
| 115 | const deadline = Date.now() + 45000; |
| 116 | while (Date.now() < deadline && !page) { |
| 117 | page = windows.find((item) => |
| 118 | item && !item.isClosed() && item.url().startsWith("a0app://content/") |
| 119 | ) || null; |
| 120 | if (!page) { |
| 121 | await app.waitForEvent("window", { timeout: 1000 }) |
| 122 | .then((item) => windows.push(item)) |
| 123 | .catch(() => null); |
| 124 | await sleep(250); |
| 125 | } |
| 126 | } |
| 127 | |
| 128 | if (!page) throw new Error("Launcher content window did not open"); |
| 129 | |
| 130 | await page.waitForLoadState("networkidle", { timeout: 10000 }).catch(() => null); |
| 131 | await sleep(3000); |
| 132 | await page.screenshot({ |
| 133 | path: `${launcher}/output/playwright/launcher-installs.png`, |
| 134 | fullPage: false, |
| 135 | }); |
| 136 | await app.close(); |
| 137 | })(); |
| 138 | JS |
| 139 | ``` |
| 140 | |
| 141 | For docs screenshots that show the first-run runtime gate without changing the |
| 142 | real machine state, open the real Launcher page and render the real runtime-gate |
| 143 | component with a minimal demo state: |
| 144 | |
| 145 | ```js |
| 146 | await page.evaluate(async () => { |
| 147 | const { renderRuntimeGate } = await import( |
| 148 | "a0app://content/components/docker-manager/runtime-gate/runtime-gate.js" |
| 149 | ); |
| 150 | |
| 151 | renderRuntimeGate({ |
| 152 | stateLoaded: true, |
| 153 | dockerAvailable: false, |
| 154 | runtime: { |
| 155 | platform: "linux", |
| 156 | state: "not_provisioned", |
| 157 | action: "install", |
| 158 | canProvision: true, |
| 159 | setupActionLabel: "Setup Agent Zero", |
| 160 | detail: "No local container runtime was found.", |
| 161 | }, |
| 162 | versions: [{ id: "latest", availability: "available" }], |
| 163 | images: [], |
| 164 | containers: [], |
| 165 | remoteInstances: [], |
| 166 | }, { |
| 167 | refresh() {}, |
| 168 | provisionRuntime() {}, |
| 169 | openDockerDownload() {}, |
| 170 | addRemoteInstance() {}, |
| 171 | }); |
| 172 | }); |
| 173 | |
| 174 | await page.locator(".dm-runtime-gate").screenshot({ |
| 175 | path: "/home/eclypso/a0/a0-launcher/output/playwright/launcher-runtime-setup.png", |
| 176 | }); |
| 177 | ``` |