Skip to content

Agent Zero AI framework

Document Launcher setup and v2.0 upgrade path

Alessandro1d90c27f3b9c
diff --git a/README.md b/README.md
index 9b1dc4acf..0cfdbdc28 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,7 @@ Agent Zero is an open, dynamic, organic agentic framework. One Docker container
[![GitHub Sponsors](https://img.shields.io/badge/Sponsors-Thank%20you-FF69B4?style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/agent0ai)
[Install](#how-to-install) |
+[Launcher](#agent-zero-launcher) |
[What's Different](#what-makes-agent-zero-different) |
[A0 CLI](#a0-cli-connector-extend-onto-your-host-machine) |
[Docs](#documentation)
@@ -34,6 +35,14 @@ Agent Zero is an open, dynamic, organic agentic framework. One Docker container
## How To Install
+### Agent Zero Launcher
+
+Starting fresh on a new machine? Use the desktop **Agent Zero Launcher** if you want a guided app instead of manual Docker commands.
+
+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.
+
+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.
+
### macOS / Linux
```bash
diff --git a/docs/README.md b/docs/README.md
index c83dd4f47..7f43fe3eb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -12,6 +12,7 @@ docs focus on practical setup, screenshots, and user workflows.
## Quick Start
- **[Quickstart Guide](quickstart.md):** Get up and running in 5 minutes with Agent Zero.
+- **[Agent Zero Launcher](guides/launcher.md):** Use the desktop app to set up Docker, install Agent Zero, open Instances, or connect a remote Instance.
- **[First-Run Onboarding](guides/onboarding.md):** Choose Cloud or Local, add a provider key, and select main and utility models.
- **[Installation Guide](setup/installation.md):** Install scripts, updates, and advanced Docker setup (includes [How to Update](setup/installation.md#how-to-update-agent-zero)).
- **[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.
## User Guides
- **[Usage Guide](guides/usage.md):** Practical tour of Agent Zero's main workflows.
+- **[Agent Zero Launcher](guides/launcher.md):** Fresh-machine Launcher walkthrough, Docker setup gate, Installs, Instances, and docs screenshot capture with Playwright/Electron.
- **[First-Run Onboarding](guides/onboarding.md):** Set up OpenRouter, our proxy API or another provider with the guided wizard.
- **[Browser Guide](guides/browser.md):** Use the built-in Browser, live Canvas surface, annotations, screenshots, host browser mode, and extensions.
- **[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.
- [Quick Start](#quick-start)
- [Quickstart Guide](quickstart.md)
+ - [Agent Zero Launcher](guides/launcher.md)
- [First-Run Onboarding](guides/onboarding.md)
- [Installation Guide](setup/installation.md)
- [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.
- [File Browser](guides/usage.md#file-browser)
- [Memory Management](guides/usage.md#memory-management)
- [Backup And Restore](guides/usage.md#backup-and-restore)
+ - [Agent Zero Launcher](guides/launcher.md)
- [Browser Guide](guides/browser.md)
- [Desktop Guide](guides/desktop.md)
- [A0 CLI Connector](guides/a0-cli-connector.md)
diff --git a/docs/guides/launcher.md b/docs/guides/launcher.md
new file mode 100644
index 000000000..2036eb88e
--- /dev/null
+++ b/docs/guides/launcher.md
@@ -0,0 +1,177 @@
+# Agent Zero Launcher
+
+Agent Zero Launcher is the desktop app for installing, running, switching, and
+opening Dockerized Agent Zero Instances without starting from Docker commands.
+
+Use it when you are setting up a new machine, when you want a quiet inventory of
+installed Agent Zero images, or when you want one place to open local and remote
+Instances.
+
+## Start Fresh On A New Machine
+
+1. Download Agent Zero Launcher from the
+ [A0 Launcher releases](https://github.com/agent0ai/a0-launcher/releases).
+2. Open the app.
+3. If the launcher cannot reach Docker yet, follow the setup dialog.
+4. If Agent Zero is already hosted on another computer or VPS, click
+ **Add remote Instance** instead of setting up local Docker.
+
+![Launcher runtime setup dialog](../res/usage/launcher/launcher-runtime-setup.png)
+
+The first setup dialog keeps the choice simple:
+
+- **Continue** starts the local runtime setup or refreshes the runtime state.
+- **Refresh** checks again after you start Docker yourself.
+- **Add remote Instance** saves an existing Agent Zero URL and lets you use the
+ Launcher without local Docker.
+
+## Installs
+
+When Docker is ready, Launcher opens to **Installs**. This page shows official
+Agent Zero release lines and local images.
+
+![Launcher Installs view](../res/usage/launcher/launcher-installs.png)
+
+Cards usually mean:
+
+- **latest** tracks the newest published Agent Zero release image.
+- **ready** tracks the development-ready image when you intentionally work from
+ that branch.
+- Version cards such as **1.20**, **1.19**, or **1.18** are pinned release
+ images.
+- **Install** downloads an image.
+- **Run** starts an installed image as a local Instance.
+
+## Instances
+
+Open **Instances** after you run Agent Zero. This is where local containers and
+saved remote Instances live.
+
+Use the Instance card to:
+
+- open the Web UI;
+- start, stop, rename, or delete the container;
+- open logs;
+- use **Backup `/a0/usr`** to download the same user-data backup you can create
+ from Agent Zero Core;
+- use **Restore `/a0/usr`** to restore that backup zip into the selected
+ Instance;
+- open A0 CLI when the host connector is installed.
+
+Launcher keeps local Instances and remote Instances separate, so deleting a
+container is not the same as deleting a saved remote URL or a workspace backup.
+
+## Updating With Launcher
+
+For same-major Agent Zero updates, the Web UI **Self Update** is still the
+normal path.
+
+For a major image jump such as v1.20 -> v2.0, use Launcher or Docker to start a
+new v2.0 Instance, then restore a backup from the old Instance. In Launcher, the
+flow is: **Instances -> Backup `/a0/usr`** on the old v1.20 Instance, **Installs
+-> latest -> Install/Run**, then **Instances -> Restore `/a0/usr`** on the new
+v2.0 Instance. This avoids mixing an old root install with a new Docker image.
+
+See [Updating from v1.20 to v2.0](../setup/installation.md#updating-from-v120-to-v20).
+
+## Capture Launcher Screenshots With Playwright
+
+Launcher is an Electron app, so browser-only Playwright commands are not enough.
+Use Playwright's Electron bridge and the local Electron binary from the Launcher
+repo.
+
+The pattern below installs Playwright into a temporary folder outside the repo,
+launches local Launcher content, waits for the `a0app://content/` window, and
+saves a screenshot.
+
+```bash
+mkdir -p /tmp/a0-launcher-playwright
+npm install --prefix /tmp/a0-launcher-playwright playwright
+```
+
+```bash
+NODE_PATH=/tmp/a0-launcher-playwright/node_modules node <<'JS'
+const { _electron: electron } = require("playwright");
+
+const launcher = "/home/eclypso/a0/a0-launcher";
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+(async () => {
+ const app = await electron.launch({
+ executablePath: `${launcher}/node_modules/electron/dist/electron`,
+ args: [launcher],
+ env: {
+ ...process.env,
+ A0_LAUNCHER_LOCAL_REPO: launcher,
+ ELECTRON_DISABLE_SECURITY_WARNINGS: "true",
+ },
+ });
+
+ const windows = [];
+ app.on("window", (page) => windows.push(page));
+ windows.push(await app.firstWindow());
+
+ let page = null;
+ const deadline = Date.now() + 45000;
+ while (Date.now() < deadline && !page) {
+ page = windows.find((item) =>
+ item && !item.isClosed() && item.url().startsWith("a0app://content/")
+ ) || null;
+ if (!page) {
+ await app.waitForEvent("window", { timeout: 1000 })
+ .then((item) => windows.push(item))
+ .catch(() => null);
+ await sleep(250);
+ }
+ }
+
+ if (!page) throw new Error("Launcher content window did not open");
+
+ await page.waitForLoadState("networkidle", { timeout: 10000 }).catch(() => null);
+ await sleep(3000);
+ await page.screenshot({
+ path: `${launcher}/output/playwright/launcher-installs.png`,
+ fullPage: false,
+ });
+ await app.close();
+})();
+JS
+```
+
+For docs screenshots that show the first-run runtime gate without changing the
+real machine state, open the real Launcher page and render the real runtime-gate
+component with a minimal demo state:
+
+```js
+await page.evaluate(async () => {
+ const { renderRuntimeGate } = await import(
+ "a0app://content/components/docker-manager/runtime-gate/runtime-gate.js"
+ );
+
+ renderRuntimeGate({
+ stateLoaded: true,
+ dockerAvailable: false,
+ runtime: {
+ platform: "linux",
+ state: "not_provisioned",
+ action: "install",
+ canProvision: true,
+ setupActionLabel: "Setup Agent Zero",
+ detail: "No local container runtime was found.",
+ },
+ versions: [{ id: "latest", availability: "available" }],
+ images: [],
+ containers: [],
+ remoteInstances: [],
+ }, {
+ refresh() {},
+ provisionRuntime() {},
+ openDockerDownload() {},
+ addRemoteInstance() {},
+ });
+});
+
+await page.locator(".dm-runtime-gate").screenshot({
+ path: "/home/eclypso/a0/a0-launcher/output/playwright/launcher-runtime-setup.png",
+});
+```
diff --git a/docs/guides/self-update.md b/docs/guides/self-update.md
index 22e490a09..e52b6a438 100644
--- a/docs/guides/self-update.md
+++ b/docs/guides/self-update.md
@@ -10,6 +10,8 @@ For day-to-day upgrades inside a running instance:
The UI will tell you when a new A0 update is available for download. Backups are automatically managed internally during the update process.
+![Self Update modal showing the current v2.0 state](../res/usage/updating/self-update-v2-current.png)
+
---
## Technical reference
@@ -71,6 +73,24 @@ Self-update is intentionally limited to changes within the same major line.
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.
+## v1.20 to v2.0
+
+Use the Docker image update path for v1.20 -> v2.0. Self Update can show that a
+newer major release line exists, but it intentionally keeps the version selector
+inside the current major line.
+
+![Self Update warning for a newer major release line](../res/usage/updating/self-update-v1-to-v2-warning.png)
+
+The important part is moving a backup zip into a fresh v2.0 container:
+
+1. In the old v1.20 Web UI, create a backup from **Settings -> Check for Updates -> Backup & Restore -> Create Backup**.
+2. Pull `agent0ai/agent-zero:latest` in Docker Desktop or Docker CLI. For the v2.0 release, `latest` is the v2.0 image.
+3. Start a new container from that image, or use the **latest** card in **Agent Zero Launcher**.
+4. Restore the downloaded backup zip into the new v2.0 Instance.
+5. Verify the new Instance before deleting the old v1.20 container.
+
+For command examples, see [Updating from v1.20 to v2.0](../setup/installation.md#updating-from-v120-to-v20).
+
## Safety notes
- Gitignored paths are preserved during update
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 4d31103f9..6f568dc80 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -7,6 +7,10 @@ Agent Zero, add a model or API key, open the Web UI, and give it a concrete job.
Run one command; the script handles Docker, image pull, and container setup.
+Prefer a desktop app on a fresh machine? Start with
+[Agent Zero Launcher](guides/launcher.md). It can set up the local runtime,
+download Agent Zero, open Instances, or save a remote Instance URL.
+
**macOS / Linux:**
```bash
curl -fsSL https://bash.agent-zero.ai | bash
diff --git a/docs/res/usage/launcher/launcher-installs.png b/docs/res/usage/launcher/launcher-installs.png
new file mode 100644
index 000000000..01f90fe78
Binary files /dev/null and b/docs/res/usage/launcher/launcher-installs.png differ
diff --git a/docs/res/usage/launcher/launcher-runtime-setup.png b/docs/res/usage/launcher/launcher-runtime-setup.png
new file mode 100644
index 000000000..fc1029bec
Binary files /dev/null and b/docs/res/usage/launcher/launcher-runtime-setup.png differ
diff --git a/docs/res/usage/updating/self-update-v1-to-v2-warning.png b/docs/res/usage/updating/self-update-v1-to-v2-warning.png
new file mode 100644
index 000000000..1454ea2f8
Binary files /dev/null and b/docs/res/usage/updating/self-update-v1-to-v2-warning.png differ
diff --git a/docs/res/usage/updating/self-update-v2-current.png b/docs/res/usage/updating/self-update-v2-current.png
new file mode 100644
index 000000000..f593adf5d
Binary files /dev/null and b/docs/res/usage/updating/self-update-v2-current.png differ
diff --git a/docs/setup/installation.md b/docs/setup/installation.md
index f4836a980..8ccc4059b 100644
--- a/docs/setup/installation.md
+++ b/docs/setup/installation.md
@@ -44,6 +44,54 @@ You'll also be prompted through the UI when a new A0 version is released. Backup
For technical details of the updater, see [Self Update](../guides/self-update.md).
+### Updating from v1.20 to v2.0
+
+Agent Zero v2.0 starts a new major release line. If your instance is on v1.20,
+the in-app Self Update can show the newer v2.x line, but it will not apply that
+jump inside the existing v1 Docker image. The safe path is:
+
+1. Create a backup zip from the old v1.20 instance.
+2. Pull the new `agent0ai/agent-zero:latest` Docker image. For the v2.0 release,
+ `latest` is the v2.0 image.
+3. Start a new container from that image.
+4. Restore the backup zip into the new v2.0 instance.
+
+![Self Update warning for a newer major release line](../res/usage/updating/self-update-v1-to-v2-warning.png)
+
+#### Without Agent Zero Launcher
+
+Use this path if you manage Agent Zero directly from Docker Desktop or Docker
+CLI.
+
+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.
+2. Pull the v2.0 image. In **Docker Desktop**, search for `agent0ai/agent-zero:latest` and pull that image. In **Docker CLI**, run:
+ ```bash
+ docker pull agent0ai/agent-zero:latest
+ ```
+3. Start a new v2.0 container on a different host port so the old instance stays available:
+ ```bash
+ docker run -d -p 50081:80 --name agent-zero-v2 -v a0_v2_usr:/a0/usr agent0ai/agent-zero:latest
+ ```
+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**.
+5. Verify chats, projects, memory, settings, and custom plugins before removing the old v1.20 container.
+
+#### With Agent Zero Launcher
+
+Launcher gives you the same backup/restore idea from the **Instances** page.
+
+1. Open **Instances**, choose the old v1.20 Instance, and use **Backup `/a0/usr`**.
+2. Open **Installs**, use the **latest** card, then **Install** or **Run** the image. For the v2.0 release, **latest** is the v2.0 image.
+3. Return to **Instances**, choose the new v2.0 Instance, and use **Restore `/a0/usr`** with the backup zip.
+4. Open the new Instance and verify it before deleting or stopping the old v1.20 container.
+
+Launcher keeps old and new Instances visible separately, which makes it easier
+to compare them before cleanup.
+
+> [!CAUTION]
+> Do not try to solve the v1.20 -> v2.0 jump by bind-mounting the whole old
+> `/a0` directory into a new container. Keep user data under `/a0/usr`, use the
+> backup/restore flow, and let the new image provide the v2.0 system files.
+
### Updating from Pre-v0.9.8
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
1. Keep the current container running
2. `docker pull agent0ai/agent-zero:latest`
-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`
-4. On the **old** instance: **Settings -> Backup & Restore -> Create Backup**
-5. On the **new** instance: **Restore** the backup
+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`
+4. On the **old** instance: **Settings -> Check for Updates -> Backup & Restore -> Create Backup**
+5. On the **new** instance: restore the downloaded backup zip
6. Verify chats and data, then remove the old container
> [!CAUTION]