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.

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

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)

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",
+});
+```

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

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

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`
+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 -> Backup & Restore -> Create Backup**
+4. On the **old** instance: **Settings -> Check for Updates -> Backup & Restore -> Create Backup**
-5. On the **new** instance: **Restore** the backup
+5. On the **new** instance: restore the downloaded backup zip
 6. Verify chats and data, then remove the old container
 
 > [!CAUTION]