Agent Zero · main guide

When something goes wrong

Agent Zero works inside its container with Host access off, and the jobs in Ten jobs for your agent stay in that workspace and in the browser. If it has already done something you did not want, read After it does something wrong.

These checks match the notes from 14 November 2026. If Agent Zero is not installed yet, go back to guide/02 and finish that setup first.

The free answers stop

A long day of jobs can use up your free tier with Google, Groq, or Z.AI, and once that happens the agent stops finishing work.

Google shows its cap for each model only inside AI Studio, Groq does not publish its free cap, and Z.AI lists its limit in its console.

The simplest fix is to wait and try the job again later, although this guide does not name a clock for when the free answers return.

If waiting is not enough, switch to the light hybrid in guide/01, which costs about $17 a month.

What you should see the agent stops completing jobs. A new request does not come back as a finished file.

The agent keeps repeating itself

Sometimes the agent gets stuck and runs the same step around and around without getting anywhere.

While a run is going, the page shows Pause and Stop. Press Stop, and then send a smaller job with one finished file and one place to save it.

If you cannot find Stop, stop the run in the chat page and start that smaller job.

What you should see the run ends, and the page accepts a new message.

Docker will not start

If Launcher cannot reach Docker, it opens a setup dialog instead of starting the container.

What you should see three choices, Continue, Refresh, and Add remote Instance.

For the computer in front of you, choose Continue, which starts or refreshes the setup on this computer. Refresh is for after you have started Docker yourself, and Add remote Instance is for a Linux computer that is already running on another machine.

On Windows, the setup may ask to turn on WSL2 and to approve the change, the same kind of prompt you saw in the first setup. The computer may also need a restart, and after it restarts, open Launcher again.

What you should see a prompt to set up WSL2, a prompt to approve the change, or a request to restart. After that, Launcher can show Running.

On a Mac, if Docker is missing, the setup can install Colima, a stand-in for Docker, and run the container with that instead.

What you should see Launcher gets past the Docker dialog and shows Running. Then Open UI opens the chat.

It asks to use your real computer

The agent may ask for your own files, or Launcher may offer Host access. Host access starts off, so leave it that way, and if the agent asks to turn it on during a run, click Stop.

The launcher notes describe a folder control, but that control only chooses the folder where file work and commands start. It does not keep commands inside that folder.

Before you ever change this, read Safety versus capability, which explains what you would gain and what you would put at risk.

What you should see Host access still off. New files appear in the workspace. Your Documents folder is unchanged.

If a different program fits better

Agent Zero scored highest, but Atomic Agent is only about a point and a half behind and Hermes Agent about two points behind, so these are near-ties rather than failed products.

Goose, if you want a normal desktop app that works on your real files, and you will not text it from a phone. By default, Goose can change those files without asking, and that includes deleting them.

Atomic Agent, if you want the program to ask before risky commands, and you have a Windows PC or a Mac with Apple Silicon. It is a developer preview, so the screens can still change, and a yes still runs as you, on your real account.

Hermes Agent, if you want phone chat and schedules on the real computer, which is also where its usual commands run. The phone chat and the schedules both need that computer to stay on.

Each of these, and six more, has its own setup page. Start with Other agents you can use instead, which compares all of them in one table.

Update it safely

Back up first, then update. Read the release notes before you apply anything. A past update pauses Telegram when an older copy saved those settings on one project or one profile, until you review the copies. This guide could not confirm that an update resets any other setting.

  1. Copy the mapped data folder before you change the container. With Launcher's default workspace, that folder is ~/agent-zero/<instance>/usr on your computer, mounted at /a0/usr in the container. It holds settings.json, secrets.env, chats/, memory, projects, and the workspace. If you started with the direct Docker command, the data is in the named volume a0_usr, also mounted at /a0/usr. Create a backup zip from Settings → Check for updates → Backup & Restore → Create Backup, or use Backup /a0/usr on the instance menu in Launcher. Backup archives do not always include /a0/usr/secrets.env, so keep a separate copy of secrets.env too. A copy of the host folder can live in Windows File History or Previous Versions, or in Mac Time Machine.

What you should see a backup zip and a copy of secrets.env on your computer, with ~/agent-zero/<instance>/usr or a0_usr still in place.

  1. For an update on the same major version, open Settings → Check for updates (called Update in the Self Update guide), find Self Update, click Review Update, and click Restart and Update. Self Update keeps /a0/usr on the container you already run, so your mapped folder or a0_usr volume stays in place. If the release notes require a new Docker image, pull agent0ai/agent-zero:latest, stop and remove the old container, and start the new image with the same /a0/usr mount. docker rm leaves the mapped folder and the named volume in place. When your data is in a0_usr, keep that volume on the new container:
docker pull agent0ai/agent-zero:latest
docker stop <container>
docker rm <container>
docker run -d -p 127.0.0.1:5080:80 -v a0_usr:/a0/usr agent0ai/agent-zero:latest

<container> is the name from docker ps.

When your data is in the mapped folder, mount the full path of ~/agent-zero/<instance>/usr at /a0/usr instead of a0_usr. In Launcher, open Versions (called Installs in older Launcher notes), use latest → Install or Run with a separate instance folder, then open Instances and use Restore /a0/usr on the new instance with your backup zip and secrets.env copy. Check the new instance before you delete the old one, do not mount the whole /a0 directory, and never start a container without /a0/usr persistent storage.

What you should see the page loads again, the instance says Running, and your old chats and settings are still there.

  1. Open Settings → Check for updates → Self Update, click Review Update, and check the Current version. Then ask for one small file in the workspace, such as a three-line note saved only there.

What you should see Current matches the release you chose, and the new note appears in the workspace while your Documents folder is unchanged.

Uninstall or reset it cleanly

  1. Stop Agent Zero before you remove it. In Launcher, open Instances and click Stop on that instance's menu. If you use Docker commands, run docker ps, then run docker stop <container> with that container name.

What you should see the instance no longer says Running.

  1. Remove the container and the image next, while keeping your data in place first. In Launcher, open the instance menu on Instances, click Delete, and choose Keep folder or Keep volume, then remove the downloaded version in Versions or remove agent0ai/agent-zero in Docker Desktop. With Docker commands, run docker rm <container> and docker rmi agent0ai/agent-zero:latest, which leave the host folder and a0_usr untouched. On Windows, uninstalling Agent Zero Launcher in Windows Settings removes the app and %APPDATA%\a0-launcher without deleting ~/agent-zero; on a Mac, this guide could not confirm a separate uninstaller beyond removing the app from Applications.

What you should see the instance is gone from Instances, and the folder ~/agent-zero/<instance>/usr or the volume a0_usr is still there.

Deleting the data folder or volume erases settings, memory, chats, and the keys in secrets.env, and this guide cannot promise you can get them back. Skip step 3 if you might want this Agent Zero data again.

  1. When you are sure you want the data gone, delete ~/agent-zero/<instance>/usr on your computer (or choose Delete folder or Delete volume if you have not deleted the instance yet). If you kept a Docker volume, remove it in Launcher under Advanced → Storage volumes, in Docker Desktop under Volumes, or with docker volume rm a0_usr. Do not delete your Documents folder.

What you should see that data folder or volume is gone, and your own Documents folder is still there.

Sources

Checked 14 November 2026.

Checked 14 November 2026 · prices, limits, and versions change