Short answer
To self-host Agent Zero, rent a 64-bit Linux VPS (the project's minimum is 1 vCPU and 2 GB RAM, 2 vCPU and 4 GB recommended), install Docker, and run the agent0ai/agent-zero image with the /a0/usr folder on a volume. Set a login in Settings, then put HTTPS in front of it.
What you are actually hosting
Agent Zero (agent0ai/agent-zero on GitHub) is a general-purpose agent. You give it a goal in a web dashboard, and it plans the steps, runs code in a Linux environment, uses a browser inside its container, and reports back. You supply the model.
Because the agent runs code, "self-hosting" here means hosting a machine that can do things, not just a web page. The project's own docs say never to expose an instance to the internet without Web UI authentication turned on, and updates matter: recent releases include an SSRF fix tracked as CVE-2026-4308 in v2.9 and security fixes for the Telegram, WhatsApp and IMAP connectors in v2.12 (a webhook authentication bypass, a media path traversal and a sender whitelist bypass).
For a side-by-side with another agent, see Agent Zero vs OpenClaw hosting. For what running any agent on a server involves, see the AI agent VPS guide.
Hardware and Docker requirements
The project's VPS deployment guide gives the numbers. As of November 2026 they are:
- CPU: 1 vCPU minimum, 2 or more recommended.
- RAM: 2 GB minimum, 4 GB or more recommended.
- Disk: 20 GB minimum, 50 GB or more recommended.
- OS: 64-bit Linux, such as Ubuntu 22.04 or newer.
- Docker: Docker Engine 24.0 or newer is the project's minimum. For the loopback port binding used in this guide, install Docker Engine 28.0.0 or newer: Docker's port publishing page says that before 28.0.0, other hosts on the same network segment could reach a port published to
127.0.0.1. - Network: a static IP and, if you want a proper address, a domain you control.
Treat the minimum as a floor for trying it out; for real browsing or heavier work, start at 2 vCPU and 4 GB.
You do not need a GPU. Agent Zero sends its model calls to a provider over the internet. A GPU only matters if you run a local model on the same machine. Our guide on whether you need a GPU to run an AI agent covers that decision.
Docker's install page lists Ubuntu 22.04, 24.04, 26.04 and 26.10 as supported and says its convenience script is only recommended for testing and development, so use the apt repository method on a machine you plan to keep.
Laptop Docker, a VPS or a managed host
| Laptop with Docker | Your own VPS | Managed host (Hivra) | |
|---|---|---|---|
| Setup | One docker run, or the A0 Launcher | Server, Docker, firewall, login, HTTPS, updates | No server to prepare |
| Stays on when you close the lid | No, the container stops when the machine sleeps or shuts down | Yes, if the container restarts after a reboot | The computer stays on while your plan is active |
| Reachable from other devices | Only from the laptop itself, because the port is bound to loopback; other devices need a tunnel or a LAN binding you set up yourself | Yes, through your domain | Yes, through a browser |
| Who secures it | You, but it is not exposed by default | You, and it faces the internet | The dashboard sits behind an authenticated gateway |
| Who updates it | You, with Self Update or a new image | You | Check Hivra's Agent Zero page for how updates work |
| Cost before model usage | Free if you already own the machine | Whatever the server costs; the specs above set the price | $9.99 a month for 2 vCPU and 4 GB of RAM |
Model usage is extra everywhere. Start on a laptop; move to a VPS if you want the agent working while you are away. The rest of this guide is the VPS route, and its checklist is: loopback port binding, a login confirmed with a 302 to /login, HTTPS through a proxy with WebSocket support, a spending limit at your model provider, and a backup of /a0/usr stored off the server.
Step 1: prepare the server
Create a 64-bit Ubuntu server with at least the specs above, then SSH in with a normal sudo user and keys. Install Docker from Docker's apt repository using the official steps, then check it works. A new sudo user is not in the docker group, so the commands in this guide start with sudo. (Adding yourself to the docker group removes the need, but anyone in that group effectively has root on the server, so we leave it out.)
sudo docker --version
sudo docker run hello-world
Open only what you need in your server's firewall: SSH, plus ports 80 and 443 once you add HTTPS below. Do not open the Agent Zero port itself, and keep any local model server port (Ollama uses 11434) private too. The next section binds Agent Zero to the server's own loopback address so nothing outside can reach it directly.
Step 2: run the official image
The image is agent0ai/agent-zero. The README, the install guide and the docs site all show docker run -d -p 127.0.0.1:5080:80 -v a0_usr:/a0/usr agent0ai/agent-zero (add sudo on a server), which publishes the port to the local machine only. For a VPS, add a name and a restart policy, which the project's own VPS guide uses too:
sudo docker pull agent0ai/agent-zero
sudo docker run -d \
--name agent-zero \
--restart unless-stopped \
-p 127.0.0.1:5080:80 \
-v a0_usr:/a0/usr \
agent0ai/agent-zero
-d runs it in the background, and --restart unless-stopped brings it back after a crash or a reboot. -p 127.0.0.1:5080:80 maps port 5080 on the server's loopback address to the container's port 80, where the web UI always listens (the project's examples use host ports 5080 and 50080, and you can pick another). -v a0_usr:/a0/usr keeps your data in a named Docker volume, so replacing the container does not delete it.
Docker's documentation says published container ports are reachable from the outside world, and that publishing to 127.0.0.1 restricts them to the host. Without the 127.0.0.1: prefix, -p 5080:80 puts an unauthenticated agent on the public internet.
The project also offers a terminal installer for servers, curl -fsSL https://bash.agent-zero.ai | bash, with a headless --quick-start mode, and a desktop app, the A0 Launcher. The plain docker run above is easier to audit, and the rest of this guide assumes it.
To see the dashboard before you add HTTPS, tunnel to it from your own computer:
ssh -L 5080:127.0.0.1:5080 you@your-server
Then open http://localhost:5080 in your browser. Nothing is exposed while you do this.
Where your data and settings live
Everything that is yours lives in one folder inside the container: /a0/usr. The install guide says it holds settings, chats, memory, projects and custom plugins, and the troubleshooting page puts chat history in /a0/usr/chats/.
Map only /a0/usr. The install guide warns that mapping the whole /a0 directory can break upgrades, because it contains the application code.
On the .env file, be careful, because the project's pages are not fully consistent. The v2.15 release notes (November 2026) say an existing usr/.env is kept authoritative during startup migration without overwriting conflicting legacy files. But the VPS deployment guide still mounts a separate .env file at /a0/.env, and the install guide mentions an .env file without giving its full path.
So check your own version before relying on either path: after any upgrade, look at what is actually there with sudo docker exec -it agent-zero ls -a /a0/usr. Secrets are a separate case. The troubleshooting page says they live in /a0/usr/secrets.env, and that backups do not always include them, so keep your own copy.
Set a login before you expose it
Do this before anything else leaves your server. The docs say: "never expose the instance to the internet without Web UI authentication enabled." The dashboard controls an agent that can run code, so an open port is an open shell.
Over your SSH tunnel, open Settings, then Authentication. There are three fields: a UI login username, a UI password, and a root password for SSH access to the container. Set a long, unique UI password and save. The sharing guide gives the same path and says to enable authentication before exposing the instance to the internet.
The project's VPS guide describes another route: AUTH_LOGIN (the username) and AUTH_PASSWORD set in an .env file, followed by a restart, and it advises at least 8 characters and avoiding the characters ' " \ and $ in the password. That guide's own check is a 302 redirect to /login from curl -I on the container's host port. With the mapping above, curl -I http://127.0.0.1:5080/ should do the same instead of serving the dashboard.
The built-in Flare Tunnel is a quick share only: the docs warn that anyone with the tunnel URL can try to open your instance.
HTTPS with a reverse proxy
A login over plain HTTP sends your password in the clear, so put HTTPS in front. The project's guide shows Apache with Let's Encrypt; Caddy is shorter because it gets and renews certificates itself. Point a DNS A record for your domain at the server, open ports 80 and 443, install Caddy, and use a Caddyfile like this:
agent.example.com {
reverse_proxy 127.0.0.1:5080
}
Reload Caddy and open https://agent.example.com. Caddy's documentation says it serves HTTPS automatically when it knows the domain name, with ports 80 and 443 open to the public, and that reverse_proxy supports WebSocket connections. The project's own guide tests WebSockets with wscat -c wss://<domain>/ws.
With Nginx or Apache instead, pass WebSocket upgrade headers through. Once HTTPS works and the login is confirmed, close your SSH tunnel and use the domain.
Choosing a model provider
Agent Zero needs a model. On first run, onboarding offers three paths:
- Cloud: paste an API key for a hosted provider such as OpenRouter, OpenAI, Anthropic, Google or Venice.
- Account: sign in with an existing account, such as Codex with ChatGPT, GitHub Copilot, Google Cloud Gemini or xAI Grok.
- Local: point it at a model server you run, such as Ollama, LM Studio, oMLX, llama.cpp or vLLM. Inside the container,
localhostmeans the container itself, and the plain Linuxdocker runabove does not add the host alias that Agent Zero's Ollama default expects. Follow the networking steps in the project's installation guide, use an address Docker can reach, and keep port 11434 closed to the public.
You pick a main model and a utility model. The utility model handles quick internal jobs such as summaries, naming and memory, and the docs recommend a small, fast, low-cost one.
Three gotchas from the troubleshooting page. Chat input does nothing until you have finished model setup in Settings, which means a key for a hosted provider, an account sign-in, or a reachable local model. "Invalid model ID" usually means the provider and model name do not match: OpenRouter needs a prefix such as openai/gpt-5.3, while the native OpenAI provider does not. And a ChatGPT Plus subscription does not include API credits, so for the OpenAI API you need your own API key.
Put a spending limit on the provider account too, because an agent stuck in a loop costs real money (our guide to cutting API costs covers where it goes). For the wider safety picture, read is it safe to leave an AI agent running unattended.
Updating Agent Zero
For normal releases, use the built-in updater: Settings, then Update, then Self Update. The updating guide and the install guide describe it, and the app prompts you when a new version ships. The install guide says backups are managed internally during the update, but take your own backup first anyway.
A major version is different. Self Update can flag a newer major line, but for the jump from v1 to v2 the docs say you must pull the new image and move your data across. The same manual method works any time you want a safe rollback:
sudo docker pull agent0ai/agent-zero:latest && \
sudo docker run -d --name agent-zero-new \
--restart unless-stopped \
-p 127.0.0.1:5081:80 \
-v a0_usr_new:/a0/usr \
agent0ai/agent-zero:latest
The && means the new container only starts if the pull worked, so you never test a stale cached image by mistake. Confirm it is up with sudo docker ps --filter name=agent-zero-new before you touch the old one. If it isn't listed, run sudo docker ps -a --filter name=agent-zero-new: no entry means the pull failed, so retry it; an exited entry means it failed to start (a port already in use, for example), so read sudo docker logs agent-zero-new, fix the cause, remove it with sudo docker rm agent-zero-new and run the command again. Your old container keeps serving the whole time.
Once the new one is up, freeze the old one so no chat is lost: let any running task finish, set each scheduled task to Disabled (note which ones) and stop chatting, then create and download a fresh in-app backup, then run sudo docker stop agent-zero. Your public address is down from here until the switch, so pick a quiet moment. Open the new one over a tunnel on port 5081 and restore that backup into it through Backup & Restore. If you set your login with AUTH_LOGIN and AUTH_PASSWORD in /a0/.env, set it again in the new one under Settings, then Authentication: that file sits outside /a0/usr, so neither the volume nor the backup carries it. Then check four things: the new container runs the image you just pulled (the IDs from sudo docker inspect --format '{{.Image}}' agent-zero-new and sudo docker image inspect --format '{{.Id}}' agent0ai/agent-zero:latest match), your chats and memory are there, the login page still appears (a 302 to /login from curl -I http://127.0.0.1:5081/), and a test prompt gets a model reply. The troubleshooting page says backups do not always include secrets.env, so if the model call fails, re-enter your provider key in Settings or copy /a0/usr/secrets.env over from the old container. Next, change the Caddyfile to reverse_proxy 127.0.0.1:5081, reload Caddy, and test your HTTPS address. Keep the old container (stopped, data intact) until that works, then remove it. Then set the scheduled tasks you disabled back to Idle on the container you keep, whether that is the new one or, after a rollback, the old one. If the new one fails while the old container still exists, start the old container again, point Caddy back at the port it used (5080 the first time; note the live name and port before every upgrade), reload Caddy, and check your HTTPS address loads before you call the rollback done. Anything chatted on the new one in between stays on its volume, so run that HTTPS check straight after the switch, before you use the agent. After the switch, your live container is agent-zero-new with the volume a0_usr_new, so use those two names wherever the commands below say agent-zero and a0_usr. For the next upgrade after that, treat whichever container is live as the old one and pick a name, port and volume you have not used yet (for example agent-zero-v3, 5082 and a0_usr_v3).
Do not copy the update command in the VPS guide verbatim: its final line is malformed, so write the full command yourself as above. And stay current: an old version on a public server is the risk you took on by self-hosting.
If an update leaves the UI stuck on the updating screen, the troubleshooting page says to reload, then restart the container, and if that fails to queue another self-update and read its log:
sudo docker exec -it agent-zero /exe/trigger_self_update.sh
sudo docker restart agent-zero
sudo docker exec -it agent-zero tail -n 200 /exe/a0-self-update.log
sudo docker exec -it agent-zero cat /exe/a0-self-update-status.yaml
The script only schedules the update, so the restart comes before you read the log and status: they report on the attempt made at that startup.
Backing up the usr folder
Your agent's memory, chats, projects, plugins and settings are all in /a0/usr, so that is the one thing to back up. There are two layers.
In the app. Settings, then Backup & Restore, then Create Backup (the install guide lists it under Settings, then Check for Updates, so look there if you do not see it). The usage guide says backups cover chats, projects, knowledge, memory, settings, skills and workspace files, and that secrets may not always be included. Download the zip and keep it off the server.
At the volume. A plain Docker volume copy does not depend on the app. This is a standard Docker pattern, not an Agent Zero command:
mkdir -p ~/a0-backups && chmod 700 ~/a0-backups && \
sudo docker stop agent-zero && \
sudo docker run --rm -v a0_usr:/data -v ~/a0-backups:/backup alpine \
tar czf "/backup/a0_usr-backup-$(date +%F-%H%M).tar.gz" -C /data .
sudo docker start agent-zero
sudo chown "$USER": ~/a0-backups/a0_usr-backup-*.tar.gz
chmod 600 ~/a0-backups/a0_usr-backup-*.tar.gz
Stopping the container first means no file changes while tar runs, so the copy is consistent. The && chain means nothing is stopped unless the private folder is ready, and the copy only runs if the stop worked. The chown hands the root-written archive back to you so you can copy it off the server. If tar printed an error (a full disk, say), delete that file: it is incomplete, and your previous dated backup is still the good one. The archive gets a new dated name each time, so an earlier backup is never overwritten, and it holds your provider key in secrets.env, which is why it goes in a folder only you can open and is set to owner-only. If the copy fails, run sudo docker start agent-zero anyway and keep your previous backup. Copy the file to another machine or storage you control; a backup on the same server will not survive losing it. Test a restore once, on a throwaway volume that never touches the live one:
sudo docker rm -f agent-zero-test 2>/dev/null; sudo docker volume rm a0_usr_test 2>/dev/null
sudo docker volume create a0_usr_test && \
sudo docker run --rm -v a0_usr_test:/data -v ~/a0-backups:/backup alpine \
tar xzf /backup/a0_usr-backup-YYYY-MM-DD-HHMM.tar.gz -C /data && \
sudo docker run -d --name agent-zero-test -p 127.0.0.1:5090:80 \
-v a0_usr_test:/a0/usr agent0ai/agent-zero:latest
Open port 5090 over your tunnel, check your chats and memory are there, then remove the test container and the a0_usr_test volume.
Common failures and fixes
- The page will not load. You need a host port mapped to container port 80. Check
sudo docker psshows127.0.0.1:5080->80/tcp, then test withcurl -I http://127.0.0.1:5080/. A 302 to/loginmeans it is up. - 502 or 504 from the proxy. A 502 means the container is stopped or the port is wrong: run
sudo docker psandsudo docker logs agent-zero. A 504 means the container is overloaded or unresponsive: runsudo docker stats, and resize the server if a 2 GB machine is full. - Settings will not load. The install guide says to remove
/a0/usr/settings.jsonand restart to regenerate defaults. Copy the file aside first (for example tosettings.json.bak) so you can put it back if the reset does not help. - Login behaves oddly after an upgrade. Check where your
.envlives, as covered above, and restart the container after any change.
Never publish the port to the whole internet just to test. Use the SSH tunnel.
Running Agent Zero on Hivra instead
Everything above is a job you do once and then keep doing: patching the server, watching disk and memory, keeping the login and certificates healthy. Hivra provisions the machine and the container for you, so there is no server for you to run, and you are not tied to one agent: the same account can run Agent Zero today and a different agent tomorrow.
- More than one agent. The same Hivra account launches Hermes, OpenClaw, Claude Code, Codex and Agent Zero, each on a computer of its own, and you reach them from a browser. If Agent Zero turns out not to be the right fit, you switch agents on the same account instead of rebuilding a server.
- The real Agent Zero. Hivra hosts the open-source stack in its own container on a separate VM, with the browser and computer tools the project supplies, and you use Agent Zero's native dashboard.
- A protected dashboard. It is reached through an authenticated gateway, with login details created during provisioning, so there is no Docker install, proxy or certificate for you to get wrong.
- Your choice of model. Set your own provider in Agent Zero's Settings, or pay with Hivra credits where they are available.
- It stays on. Paid Hivra computers are not paused for inactivity, so the environment is still there after you close the page.
- Your own server. Agent Zero can also run on a Proxmox server you connect, and a free account works with a server you connect yourself.
Every computer Hivra Cloud runs for you needs a paid plan. Plans start at $9.99 a month for 2 vCPU and 4 GB of RAM, or $19.99 a month for 4 vCPU and 8 GB of RAM. Agent Zero's minimum on Hivra is 1 vCPU and 2 GB of RAM, so the entry plan leaves room, though heavier browser use needs more.
Honest limits. Hivra is independent and not affiliated with or endorsed by the Agent Zero project. The VM keeps the agent apart from your own computer, but that does not remove the risks of agent mistakes or credentials with too much access, and Hivra administrators have infrastructure access to managed hosts, so keep keys tightly scoped. Backups are not something Hivra promises, so keep your own copy of anything important. If you want full control of the network layer, firewall rules, or a specific region or provider, a VPS you run yourself fits better.
Launch Agent Zero on Hivra if you would rather spend the evening on what the agent does than on the server it runs on. See also managed vs self-hosted and Hivra vs self-hosted VPS.
Common questions
What are the requirements to self-host Agent Zero?
The project's VPS guide lists 1 vCPU and 2 GB RAM as the minimum, 2 vCPU and 4 GB or more recommended, 20 GB of disk (50 GB recommended), 64-bit Linux such as Ubuntu 22.04 or newer, and Docker Engine 24.0 or newer (28.0.0 or newer for the loopback port binding in this guide, because earlier versions let hosts on the same network segment reach a port published to 127.0.0.1). No GPU is needed unless you run a local model on the same machine.
What is the Agent Zero Docker command?
The image is agent0ai/agent-zero. The README's command is docker run -d -p 127.0.0.1:5080:80 -v a0_usr:/a0/usr agent0ai/agent-zero. On a server, add a name and a restart policy: docker run -d --name agent-zero --restart unless-stopped -p 127.0.0.1:5080:80 -v a0_usr:/a0/usr agent0ai/agent-zero.
Which port does Agent Zero use?
Port 80 inside the container. Map any host port to it, such as 5080 in the project's examples, publish it to 127.0.0.1 only, and put a reverse proxy on ports 80 and 443 in front.
Where does Agent Zero store its data?
In /a0/usr inside the container: settings, projects, memory, custom plugins and chats. Mount only that folder as a volume, never the whole /a0 directory. Secrets live in /a0/usr/secrets.env, which backups do not always include, so copy that file yourself.
How do I add a password to Agent Zero?
Open Settings, then Authentication, and set a UI login username and password. Do this before exposing it to the internet. The project's VPS guide also describes AUTH_LOGIN and AUTH_PASSWORD in an .env file. A working login redirects to /login instead of serving the dashboard.
How do I update Agent Zero in Docker?
Back up first, then use Settings, Update, Self Update for normal releases. For a major version, pull agent0ai/agent-zero:latest, start a new container on another port with a fresh volume, restore your backup into it, check your data, and only then remove the old container.
Can I run Agent Zero for free?
The software is open source and free to run. You still pay for the server if you rent one, and for model usage unless you run a local model. Some providers have free tiers, according to the project's troubleshooting page, but limits and terms are the provider's.
Is Hivra the official Agent Zero host?
No. Hivra is an independent host that runs the open-source Agent Zero project on a computer of its own and is not affiliated with or endorsed by the project.