Agent Zero AI framework
Document Launcher setup and v2.0 upgrade path
Alessandro1d90c27f3b9c
diff --git a/README.md b/README.mdindex 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[](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```bashdiff --git a/docs/README.md b/docs/README.mdindex 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.mdnew file mode 100644index 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.++++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.++++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.mdindex 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.++---## 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.++++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 updatediff --git a/docs/quickstart.md b/docs/quickstart.mdindex 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:**```bashcurl -fsSL https://bash.agent-zero.ai | bashdiff --git a/docs/res/usage/launcher/launcher-installs.png b/docs/res/usage/launcher/launcher-installs.pngnew file mode 100644index 000000000..01f90fe78Binary files /dev/null and b/docs/res/usage/launcher/launcher-installs.png differdiff --git a/docs/res/usage/launcher/launcher-runtime-setup.png b/docs/res/usage/launcher/launcher-runtime-setup.pngnew file mode 100644index 000000000..fc1029becBinary files /dev/null and b/docs/res/usage/launcher/launcher-runtime-setup.png differdiff --git a/docs/res/usage/updating/self-update-v1-to-v2-warning.png b/docs/res/usage/updating/self-update-v1-to-v2-warning.pngnew file mode 100644index 000000000..1454ea2f8Binary files /dev/null and b/docs/res/usage/updating/self-update-v1-to-v2-warning.png differdiff --git a/docs/res/usage/updating/self-update-v2-current.png b/docs/res/usage/updating/self-update-v2-current.pngnew file mode 100644index 000000000..f593adf5dBinary files /dev/null and b/docs/res/usage/updating/self-update-v2-current.png differdiff --git a/docs/setup/installation.md b/docs/setup/installation.mdindex 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. BackupFor 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.++++#### 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.8If 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 the1. Keep the current container running2. `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 zip6. Verify chats and data, then remove the old container> [!CAUTION]