Document Launcher setup and v2.0 upgrade path
Add a Launcher guide with runtime setup, Installs, Instances, and screenshot capture notes. Link the guide from README, quickstart, and docs index, and clarify the v1.20-to-v2.0 image upgrade path with backup/restore screenshots.
Alessandro committed
Jun 24, 2026 at 10:54 UTC
1d90c27f3b9cdb0e38ccd1f8d1fe3a9af932382b
10 files changed
+265
-3
README.md
+9
@@ -13,6 +13,7 @@ Agent Zero is an open, dynamic, organic agentic framework. One Docker container
13
[](https://github.com/sponsors/agent0ai)
14
15
[Install](#how-to-install) |
16
+[Launcher](#agent-zero-launcher) |
17
[What's Different](#what-makes-agent-zero-different) |
18
[A0 CLI](#a0-cli-connector-extend-onto-your-host-machine) |
19
[Docs](#documentation)
@@ -34,6 +35,14 @@ Agent Zero is an open, dynamic, organic agentic framework. One Docker container
35
36
## How To Install
37
38
+### Agent Zero Launcher
39
+
40
+Starting fresh on a new machine? Use the desktop **Agent Zero Launcher** if you want a guided app instead of manual Docker commands.
41
+
42
+Download the Launcher from the [A0 Launcher releases](https://github.com/agent0ai/a0-launcher/releases), open it, and let it check your local runtime. If Docker is missing or stopped, the Launcher offers a setup path before it downloads Agent Zero. If you already host Agent Zero elsewhere, add it as a remote Instance and use the Launcher without local Docker setup.
43
+
44
+See the [Agent Zero Launcher guide](./docs/guides/launcher.md) for the first-run walkthrough, screenshots, and the Playwright/Electron capture recipe used for documentation.
45
+
46
### macOS / Linux
47
48
```bash
docs/README.md
+4
@@ -12,6 +12,7 @@ docs focus on practical setup, screenshots, and user workflows.
12
## Quick Start
13
14
- **[Quickstart Guide](quickstart.md):** Get up and running in 5 minutes with Agent Zero.
15
+- **[Agent Zero Launcher](guides/launcher.md):** Use the desktop app to set up Docker, install Agent Zero, open Instances, or connect a remote Instance.
16
- **[First-Run Onboarding](guides/onboarding.md):** Choose Cloud or Local, add a provider key, and select main and utility models.
17
- **[Installation Guide](setup/installation.md):** Install scripts, updates, and advanced Docker setup (includes [How to Update](setup/installation.md#how-to-update-agent-zero)).
18
- **[A0 CLI Connector](guides/a0-cli-connector.md):** Install the host connector for a running Agent Zero instance, use the command palette, and switch Browser modes.
@@ -22,6 +23,7 @@ docs focus on practical setup, screenshots, and user workflows.
23
## User Guides
24
25
- **[Usage Guide](guides/usage.md):** Practical tour of Agent Zero's main workflows.
26
+- **[Agent Zero Launcher](guides/launcher.md):** Fresh-machine Launcher walkthrough, Docker setup gate, Installs, Instances, and docs screenshot capture with Playwright/Electron.
27
- **[First-Run Onboarding](guides/onboarding.md):** Set up OpenRouter, our proxy API or another provider with the guided wizard.
28
- **[Browser Guide](guides/browser.md):** Use the built-in Browser, live Canvas surface, annotations, screenshots, host browser mode, and extensions.
29
- **[Desktop Guide](guides/desktop.md):** Use the built-in Linux desktop, GUI apps, and LibreOffice Writer/Calc/Impress Cowork.
@@ -63,6 +65,7 @@ docs focus on practical setup, screenshots, and user workflows.
65
66
- [Quick Start](#quick-start)
67
- [Quickstart Guide](quickstart.md)
68
+ - [Agent Zero Launcher](guides/launcher.md)
69
- [First-Run Onboarding](guides/onboarding.md)
70
- [Installation Guide](setup/installation.md)
71
- [How to Update Agent Zero](setup/installation.md#how-to-update-agent-zero)
@@ -113,6 +116,7 @@ docs focus on practical setup, screenshots, and user workflows.
116
- [File Browser](guides/usage.md#file-browser)
117
- [Memory Management](guides/usage.md#memory-management)
118
- [Backup And Restore](guides/usage.md#backup-and-restore)
119
+ - [Agent Zero Launcher](guides/launcher.md)
120
- [Browser Guide](guides/browser.md)
121
- [Desktop Guide](guides/desktop.md)
122
- [A0 CLI Connector](guides/a0-cli-connector.md)
docs/guides/launcher.md
new
+177
@@ -0,0 +1,177 @@
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
+```
docs/guides/self-update.md
+20
@@ -10,6 +10,8 @@ For day-to-day upgrades inside a running instance:
10
11
The UI will tell you when a new A0 update is available for download. Backups are automatically managed internally during the update process.
12
13
+
14
+
15
---
16
17
## Technical reference
@@ -71,6 +73,24 @@ Self-update is intentionally limited to changes within the same major line.
73
74
If a newer major line exists, the UI points you to the Docker setup guide because those upgrades require downloading a new Docker image. They can include operating system level changes or other breaking changes outside the repository checkout.
75
76
+## v1.20 to v2.0
77
+
78
+Use the Docker image update path for v1.20 -> v2.0. Self Update can show that a
79
+newer major release line exists, but it intentionally keeps the version selector
80
+inside the current major line.
81
+
82
+
83
+
84
+The important part is moving a backup zip into a fresh v2.0 container:
85
+
86
+1. In the old v1.20 Web UI, create a backup from **Settings -> Check for Updates -> Backup & Restore -> Create Backup**.
87
+2. Pull `agent0ai/agent-zero:latest` in Docker Desktop or Docker CLI. For the v2.0 release, `latest` is the v2.0 image.
88
+3. Start a new container from that image, or use the **latest** card in **Agent Zero Launcher**.
89
+4. Restore the downloaded backup zip into the new v2.0 Instance.
90
+5. Verify the new Instance before deleting the old v1.20 container.
91
+
92
+For command examples, see [Updating from v1.20 to v2.0](../setup/installation.md#updating-from-v120-to-v20).
93
+
94
## Safety notes
95
96
- Gitignored paths are preserved during update
docs/quickstart.md
+4
@@ -7,6 +7,10 @@ Agent Zero, add a model or API key, open the Web UI, and give it a concrete job.
7
8
Run one command; the script handles Docker, image pull, and container setup.
9
10
+Prefer a desktop app on a fresh machine? Start with
11
+[Agent Zero Launcher](guides/launcher.md). It can set up the local runtime,
12
+download Agent Zero, open Instances, or save a remote Instance URL.
13
+
14
**macOS / Linux:**
15
```bash
16
curl -fsSL https://bash.agent-zero.ai | bash
docs/res/usage/launcher/launcher-installs.png
Binary files /dev/null and b/docs/res/usage/launcher/launcher-installs.png differ
docs/res/usage/launcher/launcher-runtime-setup.png
Binary files /dev/null and b/docs/res/usage/launcher/launcher-runtime-setup.png differ
docs/res/usage/updating/self-update-v1-to-v2-warning.png
Binary files /dev/null and b/docs/res/usage/updating/self-update-v1-to-v2-warning.png differ
docs/res/usage/updating/self-update-v2-current.png
Binary files /dev/null and b/docs/res/usage/updating/self-update-v2-current.png differ
docs/setup/installation.md
+51
-3
@@ -44,6 +44,54 @@ You'll also be prompted through the UI when a new A0 version is released. Backup
44
45
For technical details of the updater, see [Self Update](../guides/self-update.md).
46
47
+### Updating from v1.20 to v2.0
48
+
49
+Agent Zero v2.0 starts a new major release line. If your instance is on v1.20,
50
+the in-app Self Update can show the newer v2.x line, but it will not apply that
51
+jump inside the existing v1 Docker image. The safe path is:
52
+
53
+1. Create a backup zip from the old v1.20 instance.
54
+2. Pull the new `agent0ai/agent-zero:latest` Docker image. For the v2.0 release,
55
+ `latest` is the v2.0 image.
56
+3. Start a new container from that image.
57
+4. Restore the backup zip into the new v2.0 instance.
58
+
59
+
60
+
61
+#### Without Agent Zero Launcher
62
+
63
+Use this path if you manage Agent Zero directly from Docker Desktop or Docker
64
+CLI.
65
+
66
+1. Open your old v1.20 Web UI and create a backup from **Settings -> Check for Updates -> Backup & Restore -> Create Backup**. Keep the downloaded `.zip` file.
67
+2. Pull the v2.0 image. In **Docker Desktop**, search for `agent0ai/agent-zero:latest` and pull that image. In **Docker CLI**, run:
68
+ ```bash
69
+ docker pull agent0ai/agent-zero:latest
70
+ ```
71
+3. Start a new v2.0 container on a different host port so the old instance stays available:
72
+ ```bash
73
+ docker run -d -p 50081:80 --name agent-zero-v2 -v a0_v2_usr:/a0/usr agent0ai/agent-zero:latest
74
+ ```
75
+4. Open the new v2.0 instance, complete any first-run prompts, then restore the downloaded `.zip` from **Settings -> Check for Updates -> Backup & Restore -> Restore Backup**.
76
+5. Verify chats, projects, memory, settings, and custom plugins before removing the old v1.20 container.
77
+
78
+#### With Agent Zero Launcher
79
+
80
+Launcher gives you the same backup/restore idea from the **Instances** page.
81
+
82
+1. Open **Instances**, choose the old v1.20 Instance, and use **Backup `/a0/usr`**.
83
+2. Open **Installs**, use the **latest** card, then **Install** or **Run** the image. For the v2.0 release, **latest** is the v2.0 image.
84
+3. Return to **Instances**, choose the new v2.0 Instance, and use **Restore `/a0/usr`** with the backup zip.
85
+4. Open the new Instance and verify it before deleting or stopping the old v1.20 container.
86
+
87
+Launcher keeps old and new Instances visible separately, which makes it easier
88
+to compare them before cleanup.
89
+
90
+> [!CAUTION]
91
+> Do not try to solve the v1.20 -> v2.0 jump by bind-mounting the whole old
92
+> `/a0` directory into a new container. Keep user data under `/a0/usr`, use the
93
+> backup/restore flow, and let the new image provide the v2.0 system files.
94
+
95
### Updating from Pre-v0.9.8
96
97
If you are upgrading from Agent Zero v0.9.8 or earlier to v1.1 or newer, use the migration path below. Older installs were laid out differently, so the in-app Self Update is not the right tool for that jump.
@@ -61,9 +109,9 @@ If you are upgrading from Agent Zero v0.9.8 or earlier to v1.1 or newer, use the
109
110
1. Keep the current container running
111
2. `docker pull agent0ai/agent-zero:latest`
64
-3. Start a **new** container on a different host port, for example: `docker run -d -p 50081:80 --name agent-zero-new agent0ai/agent-zero`
65
-4. On the **old** instance: **Settings -> Backup & Restore -> Create Backup**
66
-5. On the **new** instance: **Restore** the backup
112
+3. Start a **new** container on a different host port, for example: `docker run -d -p 50081:80 --name agent-zero-new agent0ai/agent-zero:latest`
113
+4. On the **old** instance: **Settings -> Check for Updates -> Backup & Restore -> Create Backup**
114
+5. On the **new** instance: restore the downloaded backup zip
115
6. Verify chats and data, then remove the old container
116
117
> [!CAUTION]