Install OpenClaw in an Ubuntu VM with Docker Compose

This OpenClaw Docker guide runs the agent inside an Ubuntu VM. Install Docker Engine with the Compose plugin, and clone the OpenClaw repo. Then run the official setup script with a pinned pre-built image. The script asks for your model API key, creates a gateway token and starts the stack. Before you use it, bind the dashboard port to localhost and reach it over an SSH tunnel.

Who this is for: you want to try OpenClaw, the open-source personal AI agent (once called Clawdbot and Moltbot), in a setup you can throw away and rebuild.

Why a VM and Docker, not your main computer

OpenClaw connects a language model to your chat apps, your files and a shell. That power is the point, and it is also the risk. On 31 January 2026, Censys counted 21,639 OpenClaw instances reachable on the internet. In early February, security researchers reported hundreds of malicious skills on ClawHub, the public skill registry. As of 9 October 2026, the project's GitHub page lists more than 700 security advisories, most of them fixed.

None of that means "do not use it". It means "do not run it next to your personal data". Two layers help:

• The VM gives OpenClaw its own operating system, kernel and disk. Your laptop is out of reach, and snapshots let you undo anything.
• Docker inside the VM gives you a pinned image, a clear list of data folders and a one-command rebuild.

Docker alone shares the host kernel, so it isolates less than a VM. The guide to containers vs virtual machines explains the difference. Here you get both.

What you need

• A hypervisor. Proxmox VE on a spare PC, VMware Workstation or Fusion, or VirtualBox. See VMware vs VirtualBox vs Proxmox if you have not picked one. As of October 2026, OpenClaw publishes images for AMD64 and ARM64, so an ARM Ubuntu VM on an Apple Silicon Mac is a valid target.
• Ubuntu Server 24.04 LTS. The OpenClaw docs say Linux is fully supported and give Ubuntu setup steps. As of October 2026, they do not publish a tested list of distribution versions.
• A model. An API key from a provider such as Anthropic, OpenAI or OpenRouter, or a local model server such as Ollama.

VM size

OpenClaw publishes no general minimum for a Linux server. Its Raspberry Pi page states 1 GB of RAM, 1 core and 500 MB of disk as a floor. Building the Docker image from source needs at least 6 GB of RAM, but a pre-built image avoids that. The sizes below are my suggestion for a comfortable lab VM, not an official figure.

Resource	Suggested	Note
vCPUs	2	One is enough to start
RAM	4 GB	Use the pre-built image. A source build needs 6 GB or more.
Disk	32 GB	OS, Docker images, workspace and snapshots
Network	NAT	OpenClaw needs outbound access only

Step 1: Create the VM and install Docker

Create the VM, install Ubuntu Server with the OpenSSH server, and log in as your normal user. Update the system:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git

Install Docker Engine and the Compose plugin with the steps on the Docker Engine install page for Ubuntu. Use Docker's own repository, not the older docker.io package, so you get Compose v2. Check both tools:

docker --version
docker compose version

Shut down the VM and take a snapshot called docker-ready. This is your clean return point.

Step 2: Get the OpenClaw Docker Compose files

The Docker setup runs from a checkout of the official repo:

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Pick a version and pin it. As of 8 October 2026, the latest stable release was 2026.9.9. Check the releases page for the current one, and use that tag in place of latest:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:2026.9.9"

A pinned tag means the agent does not change under you when you restart. Only download images from ghcr.io/openclaw/openclaw or the openclaw/openclaw Docker Hub mirror. The docs warn against unofficial mirrors.

Step 3: Close the ports before first start

This step is not in the quick start, and it matters. Open docker-compose.yml and find the ports: block of the openclaw-gateway service. As of October 2026, it publishes three ports on every network interface:

    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
      - "${OPENCLAW_MSTEAMS_PORT:-3978}:3978"

Port 18789 serves the dashboard and the WebSocket API. Port 3978 is for Microsoft Teams. The old bridge on port 18790 is gone. Current builds use 18790 only if you turn on MCP Apps. If you do, add a second localhost line for it and tunnel it too. Change the block so the gateway listens on the VM's localhost only, and drop the ports you do not use:

    ports:
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT:-18789}:18789"

Why edit the file? The container binds the gateway to the LAN by default, and the OpenClaw security docs say so plainly. Also, ports that Docker publishes skip the host's normal firewall rules, so UFW alone does not protect them. The gateway still requires a token, but a closed port is a stronger default. Keep a note of this change, because git pull may conflict with it later.

Step 4: Run the setup script

From the repo folder, run the official script:

./scripts/docker/setup.sh

With OPENCLAW_IMAGE set, the script pulls the pre-built image instead of building one. It then asks for your model provider's API key, writes a gateway token to .env and starts the gateway with Docker Compose. The full flow is on the OpenClaw Docker page.

Check that the stack is up:

docker compose ps
docker compose logs -f openclaw-gateway

Step 5: Open the dashboard over an SSH tunnel

From your own computer, open a tunnel to the VM:

ssh -N -L 18789:127.0.0.1:18789 you@vm-address

Keep local port 18789. The setup script allows only that origin for the dashboard.

Then, in the VM, print the dashboard link:

docker compose run --rm openclaw-cli dashboard --no-open

Open the link in your browser. If the page says pairing required or unauthorized, approve your browser as a device:

docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

Add a chat channel (optional)

The docs suggest Telegram first, because it needs only a bot token. Run the CLI through Compose:

docker compose run --rm openclaw-cli channels add --channel telegram --token <bot-token>

Start the line with a space, or clear it from your shell history afterwards, so the token is not saved. Unknown senders get a pairing code by default. Leave that on.

Step 6: Harden the install

• Run the audit. docker compose run --rm openclaw-cli security audit checks your config against the safe defaults.
• Treat skills as untrusted code. The docs say to read a skill before you enable it. A clean ClawHub scan does not prove a skill is safe.
• Tighten tools with the hardened baseline. The OpenClaw security docs list it. It denies shell commands, limits file access to the workspace and turns off elevated tools. In Docker, copy only its tools and channels settings. Leave gateway.bind as lan and keep the token that setup created. A loopback bind inside the container makes the dashboard unreachable.
• Keep secrets out of the VM. Do not sign the agent into accounts it does not need.
• Leave the Docker socket mount off. It is commented out in the compose file. Mounting it gives the container control of Docker on the VM.

Snapshots, backups and rollback

OpenClaw keeps its state in three folders on the VM, mounted into the container:

• ~/.openclaw: config, the .env file and the SQLite databases
• ~/.openclaw/workspace: the agent's working files
• ~/.openclaw-auth-profile-secrets: auth profile secrets

The docs warn that OAuth tokens sit in plain text in SQLite under the config folder. Treat every copy of these folders as a password vault.

Also, never copy live .sqlite, -wal or -shm files. Stop the stack first:

docker compose down
sudo tar czf ~/openclaw-backup-$(date +%F).tar.gz ~/.openclaw ~/.openclaw-auth-profile-secrets ~/openclaw/.env ~/openclaw/docker-compose.yml
docker compose up -d openclaw-gateway

The repo's .env holds the image pin and the gateway token, so the archive is a secret. Encrypt it before it leaves the VM.

A safe upgrade routine

1. Take a VM snapshot.
2. In the repo folder, edit .env and set OPENCLAW_IMAGE to the new version tag.
3. Run docker compose pull openclaw-gateway openclaw-cli.
4. Run docker compose up -d openclaw-gateway.
5. Test one simple task.
6. If it fails, revert the snapshot. Do not just switch the tag back, because the new version may have migrated the database.

On start, the image runs openclaw doctor --fix and saves SQLite backups ending in .pre-startup-migration-<id>.bak. Still, the docs say a downgrade does not reverse config or database changes. That is why the VM snapshot is your real rollback.

Troubleshooting

Symptom	Fix
EACCES on /home/node/.openclaw	The image runs as user ID 1000. Run sudo chown -R 1000:1000 ~/.openclaw ~/.openclaw-auth-profile-secrets.
Build killed, exit code 137	Out of memory. Use a pre-built image with OPENCLAW_IMAGE.
pairing required or disconnected (1008)	Run devices list, then devices approve, as in step 5.
origin not allowed	Add your dashboard URL to gateway.controlUi.allowedOrigins.
EADDRINUSE	Another gateway uses the port. Stop it or change OPENCLAW_GATEWAY_PORT.
Config change has no effect	docker compose restart does not reload env changes. Run docker compose up -d openclaw-gateway.
Skill fails with brew not installed	The image has no Homebrew. Build a local image with OPENCLAW_IMAGE_APT_PACKAGES set (a source build needs 6 GB of RAM), or build your own image on top of the official one.

For anything else, run docker compose run --rm openclaw-cli doctor --json and read the findings. If that does not fix it, revert the snapshot and start again.

Docker or the native install?

OpenClaw also has a one-line native installer that sets up Node.js and a systemd service. On a host install, the gateway binds to loopback by default. The Docker route gives you a pinned image and easy rebuilds. The native route gives you openclaw update and fewer moving parts. In a VM, both are fine. If you also want to try Hermes Agent, read the Hermes Agent Ubuntu VM guide, then the Hermes vs OpenClaw comparison.

FAQ

What port does OpenClaw use?

The gateway uses port 18789 for the dashboard and the WebSocket API. As of October 2026, the compose file also publishes 18790 and 3978 (Microsoft Teams). Bind 18789 to localhost and reach it with an SSH tunnel or Tailscale.

How much RAM does OpenClaw need in Docker?

A pre-built image runs in far less than a source build. The docs say a source build needs at least 6 GB of RAM. For a lab VM, 4 GB with a pre-built image is a comfortable start.

Is OpenClaw safe to run?

It is as safe as your setup. Keep the gateway off the public internet, use token auth, read every skill before you enable it, and keep personal accounts out of it. A VM with snapshots limits the damage if something goes wrong.

Is a VPS better than a home VM for OpenClaw?

A VPS runs around the clock and needs no hardware at home. A home VM keeps your data on your own machine and costs nothing extra. On either, use an SSH-only firewall and never expose the gateway port directly.

Can I run OpenClaw on Proxmox?

Yes. Create an Ubuntu VM on Proxmox and follow this guide. As of October 2026, OpenClaw has no official Proxmox page, so treat the VM as any Linux Docker host. See what Proxmox VE is if you are new to it.

How do I update OpenClaw in Docker?

Take a snapshot, set the new tag in the repo's .env file, run docker compose pull, then docker compose up -d openclaw-gateway. Avoid latest, so you know which version you run.

Related guides

• Hermes vs OpenClaw on Virtual Machines: Which Fits Your Setup?
• Install Hermes Agent on an Ubuntu Virtual Machine
• Containers vs Virtual Machines: When to Use Which
• Home Server Setup: Hardware, OS and Your First Services
• What Is a Home Lab? How to Start One in 2026

Containers vs Virtual Machines: When to Use Which

The core difference in container vs virtual machine is the kernel. A virtual machine (VM) runs a full operating system on virtual hardware, with its own kernel. A container shares the host's kernel and isolates only the processes, files and network. Use a VM when you need strong isolation or a different OS. Use a container when you want to run many Linux services with little overhead.

Who this is for: you run a home lab or a small-team server, and you want to know where each workload should live.

What a virtual machine is

A virtual machine is a complete computer made of software. A hypervisor gives it virtual CPUs, memory, disks and network cards. The VM boots its own operating system, with its own kernel, from its own virtual disk. The guest OS does not know (or care) that the hardware is not real.

The hypervisor is the layer that makes this work. If you want the full picture, read how a hypervisor shares one machine between VMs. For this post, you only need one fact. Each VM carries a full OS, so each VM costs you memory, disk and boot time.

That cost buys you three things:

• Any OS. A Linux host can run Windows, BSD or a different Linux kernel in a VM.
• Strong isolation. A crash or a kernel exploit inside the VM stays inside the VM, in most cases.
• Full control. You can load kernel modules, pass through a GPU or a disk controller, and snapshot the whole machine.

What a container is

A container is a group of processes that the host kernel isolates from everything else. The kernel gives the container its own view of the file system, the process list, the network and the users. Linux does this with namespaces and control groups (cgroups). There is no second kernel and no virtual hardware.

Because there is no guest OS to boot, a container starts fast and uses little memory. You can run many more containers than VMs on the same machine. The limit is simple: a container must use the host's kernel. A Linux host runs Linux containers. It cannot run a Windows container natively.

Containers are one form of OS-level virtualization. The guide to types of virtualization shows where they sit next to server, desktop, storage and network virtualization.

Two kinds of container

Not all containers do the same job. Home lab users meet two kinds:

• System containers (LXC). An LXC container looks like a small Linux machine. It runs an init system, several services and a shell you log in to. You manage it like a lightweight VM.
• Application containers (Docker, Podman). A Docker container usually runs one application from an image. You do not log in and patch it. You replace it with a new image when an update comes out.

This split matters when you compare LXC vs Docker. They use the same kernel features, but they suit different habits. See the LXC documentation and the Docker documentation for the details of each.

Container vs virtual machine: side by side

This table sums up the trade-offs. The words "faster" and "lighter" are relative. Real numbers depend on your hardware and workload, so measure your own.

Factor	Virtual machine	System container (LXC)	Application container (Docker)
Kernel	Its own	Shared with host	Shared with host
Guest OS choice	Any OS the hypervisor supports	Linux only (on a Linux host)	Linux images on a Linux host
Isolation	Strong (hardware-level)	Good, weaker than a VM	Good, weaker than a VM
Start time	Slower (full boot)	Fast	Fast
Memory overhead	Higher (full OS)	Low	Low
How you update it	Patch the OS inside	Patch the OS inside	Pull a new image, recreate
Hardware passthrough	Yes (GPU, disks, USB, PCIe)	Limited, needs host config	Limited, needs host config
Best for	Windows, appliances, untrusted code	Small Linux services you manage by hand	Packaged apps with ready-made images

When a virtual machine wins

Pick a VM when one of these is true:

• You need a different OS. Windows, pfSense, OPNsense, TrueNAS and many appliances need their own kernel.
• You run code you do not trust. A test box for downloads or a public-facing service gets more protection in a VM.
• You need hardware passthrough. A GPU for a media server or a disk controller for a storage VM is simpler in a VM.
• You need a custom kernel. Some VPN and storage tools need kernel modules the host does not load.
• You want clean snapshots of a whole system. A VM snapshot covers the OS, the apps and the data disk together.

When a container wins

Pick a container when these are true:

• The app runs on Linux. Most self-hosted apps do.
• You want to run many small services. DNS, a reverse proxy, a dashboard and a password manager do not each need a full OS.
• You have limited memory. A mini PC or an old laptop goes much further with containers.
• The app ships as a Docker image. If the project publishes an image and a compose file, use them. You get updates the way the developers test them.

In my view, most home labs end up with a mix. A few VMs carry the heavy or sensitive jobs. Many containers carry the small services.

How Proxmox runs both

Proxmox VE is a good place to learn this, because it runs both models from one web interface. It uses KVM for virtual machines and LXC for system containers. If you are new to it, start with what Proxmox VE is and why home labs run it.

In Proxmox, you create a VM or a container from the same menu. Both get an ID, storage, a network bridge and backup jobs. The difference is under the hood. A VM gets virtual hardware. A container shares the Proxmox host kernel.

Proxmox vs Docker: the wrong question

People often search "Proxmox vs Docker". The two are not rivals. Proxmox is a platform that hosts VMs and LXC containers. Docker is a tool that runs application containers inside a Linux system. You can run Docker on Proxmox. The real question is where Docker should live.

Where to run Docker on Proxmox

You have four choices:

1. Docker inside a VM. Create a Linux VM and install Docker in it. This is the safest option. As of October 2026, the Proxmox documentation says a VM remains a recommended practice for isolation and live migration. Verify this in the Proxmox VE documentation before you decide.
2. Docker inside an LXC container. This uses less memory. It also needs extra settings (such as nesting), and updates to the host or Docker can break it. Many people run it this way. Treat it as a choice you test, not a default.
3. Docker on the Proxmox host itself. Do not do this. It mixes your app layer with your hypervisor. A bad update or a firewall rule can take down every guest.
4. OCI images as app containers. As of October 2026, Proxmox can pull an OCI image (the format Docker uses) and run it as an application container, converted to LXC. This is a technology preview, not for production. Check the Proxmox docs for its current status.

A simple pattern works for most labs. Run one Linux VM for all your Docker apps. Run LXC containers for small standalone services. Run separate VMs for Windows, firewalls and anything that needs passthrough.

Common mistakes

• Thinking a container is as isolated as a VM. It is not. All containers share one kernel. A kernel flaw can affect every container on the host. Keep risky workloads in VMs.
• Running containers as root without need. Use unprivileged LXC containers where you can. For Docker, read the security section of the Docker docs.
• Putting one app per VM by habit. Ten VMs for ten small apps wastes memory. Group small Linux apps in containers.
• Storing data inside the container. When you recreate a Docker container, data inside it goes away. Use volumes or bind mounts, and back them up.
• Skipping backups because containers are "disposable". The container is disposable. Your data and your config are not.
• Forgetting the host is a single point of failure. VMs and containers on one box all stop when the box stops. The post on disadvantages of server virtualization covers how to plan for this.

A quick way to decide

Ask these questions in order. Stop at the first "yes".

1. Does it need a non-Linux OS or its own kernel? Use a VM.
2. Does it need GPU or disk passthrough? Use a VM.
3. Is it untrusted, or exposed to the internet with no proxy in front? Use a VM.
4. Does the project ship an official Docker image? Run it in Docker, inside a VM.
5. Is it a small Linux service you want to manage like a server? Use an LXC container.

This is a starting rule, not a law. Change it when your own tests show a better fit.

FAQ

Is a container faster than a virtual machine?

A container usually starts faster and uses less memory, because it does not boot a second OS. For CPU-heavy work, the gap is often small, since modern VMs use hardware virtualization. Measure your own workload before you decide on speed alone.

Is a container more secure than a VM?

No. A VM has stronger isolation, because each VM has its own kernel. Containers share the host kernel, so one kernel flaw can reach all of them. Containers can still be safe when you keep them unprivileged and patched.

What is the difference between LXC and Docker?

Both use the same Linux kernel features. LXC runs a full Linux userland that you manage like a small server. Docker runs one packaged application from an image, and you replace the container to update it.

Can I run Docker inside a virtual machine?

Yes, and it is a common setup. You install a Linux VM, then install Docker in it. On Proxmox this keeps Docker away from the host and makes backups simple.

Can a container run Windows on a Linux host?

No. A container shares the host kernel, so a Linux host runs Linux containers. To run Windows on a Linux host, use a VM.

Do I need Proxmox to use containers?

No. You can run Docker or LXC on any Linux system. Proxmox adds a web interface, backups and VMs in one place, which helps when your lab grows.

Related guides

• What Is a Hypervisor? Type 1 vs Type 2 Explained
• What Is Proxmox VE? Why Home Labs Run It
• Types of Virtualization: Server, Desktop, Storage, Network and More
• Home Server Setup: Hardware, OS and Your First Services
• What Is a Home Lab? How to Start One in 2026
• Install OpenClaw in an Ubuntu VM with Docker Compose
• Hermes vs OpenClaw on Virtual Machines: Which Fits Your Setup?