Showing posts with label Ubuntu. Show all posts
Showing posts with label Ubuntu. Show all posts

Install OpenClaw in an Ubuntu VM with Docker Compose

Illustration of an AI agent running in Docker containers inside a virtual machine, with a locked network port

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.

ResourceSuggestedNote
vCPUs2One is enough to start
RAM4 GBUse the pre-built image. A source build needs 6 GB or more.
Disk32 GBOS, Docker images, workspace and snapshots
NetworkNATOpenClaw 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

SymptomFix
EACCES on /home/node/.openclawThe image runs as user ID 1000. Run sudo chown -R 1000:1000 ~/.openclaw ~/.openclaw-auth-profile-secrets.
Build killed, exit code 137Out 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 allowedAdd your dashboard URL to gateway.controlUi.allowedOrigins.
EADDRINUSEAnother gateway uses the port. Stop it or change OPENCLAW_GATEWAY_PORT.
Config change has no effectdocker compose restart does not reload env changes. Run docker compose up -d openclaw-gateway.
Skill fails with brew not installedThe 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

Install Hermes Agent on an Ubuntu Virtual Machine: Setup, Snapshots, and Recovery

Illustration of an AI agent running safely inside an Ubuntu virtual machine, with snapshot and rollback symbols

A Hermes Agent install on an Ubuntu virtual machine takes four steps. Create an Ubuntu 24.04 VM, install a few packages, and run the official install script. Then choose a model provider with hermes model and run the gateway as a systemd service. Take a VM snapshot before the install and another after it works. If an update or the agent itself breaks something, you revert the snapshot and start again.

Who this is for: you want to try Hermes Agent, the open-source AI agent from Nous Research, without giving it access to your main computer.

Why run Hermes Agent in a virtual machine

Hermes Agent is not a chatbot in a browser tab. It runs shell commands, edits files, keeps memory and can act on a schedule. By default it runs those commands directly on the machine where you install it. The project's own security policy is blunt about this. It says, "The only security boundary against an adversarial LLM is the operating system."

A virtual machine gives the agent its own operating system. If it deletes the wrong folder or installs something odd, the damage stays inside the VM. Your laptop, your photos and your saved browser logins are not in reach. The security docs also suggest a separate machine or VM for maximum isolation. If you want the background on why a VM isolates more than a container, read containers vs virtual machines.

A VM also gives you snapshots. A snapshot saves the whole machine at one point in time. That is the best recovery tool you have for an agent that changes its own environment.

What you need

A hypervisor

Any desktop or server hypervisor works. If you are not sure what that word means, read what a hypervisor is first. Common choices:

  • Proxmox VE on a spare PC or mini PC. Good if the agent should run around the clock. See what Proxmox VE is.
  • VMware Workstation Pro or Fusion Pro on your desktop. As of October 2026, both are free for all use. Verify this on the Broadcom site.
  • VirtualBox on Windows, Linux or macOS (check that your version supports your Mac's chip).

The guide to VMware vs VirtualBox vs Proxmox compares them for a desktop lab. On an Apple Silicon Mac, use an ARM build of Ubuntu in VMware Fusion. As of October 2026, the Hermes platform page lists Linux on both x86_64 and aarch64 as supported.

VM size

Nous Research publishes resource figures only for the Docker container. As of October 2026, those are 1 GB of RAM minimum and 2 to 4 GB recommended, 1 CPU core minimum and 2 recommended. Browser tools need at least 2 GB of RAM. A full VM also needs room for Ubuntu itself, so I suggest the sizes below. They are my suggestion, not an official figure.

ResourceSuggested VM sizeWhy
vCPUs2Matches the recommended container figure
RAM4 GBUbuntu plus the agent plus browser tools
Disk32 GBOS, runtimes, logs, sessions and snapshot headroom
NetworkNAT or bridgedThe agent needs outbound internet only
GPUNoneOnly needed if you run a local model

A model provider

Hermes Agent needs a language model. You can use a cloud provider such as OpenRouter, Anthropic, OpenAI or Nous Portal, with an API key. You can also run a local model through llama.cpp or Ollama. Note one hard rule: Hermes rejects models with less than 64,000 tokens of context. Ollama's default context is lower, so you must raise it. Check the providers page for the current list.

Step 1: Create the Ubuntu VM

Download Ubuntu Server 24.04 LTS from the Ubuntu website. Create a VM with the sizes above and install Ubuntu with default options. Turn on the OpenSSH server during setup so you can work from your own terminal.

Use Ubuntu 24.04. The Hermes docs say they test on the latest Ubuntu. As of October 2026, I found no official statement that Ubuntu 22.04 is tested.

Step 2: Prepare Ubuntu

Log in over SSH as your normal user, not root. Update the system and install the prerequisites:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl tar libatomic1

The installer needs Git, curl, tar and SHA-256 tools. Ubuntu ships the SHA-256 tools already. The libatomic1 package is there for a reason. Early installs on minimal Ubuntu 24.04 images failed silently without it. The current installer adds it for you, but installing it first costs nothing.

Step 3: Take a clean snapshot

Shut down the VM and take a snapshot. Name it something plain, such as clean-ubuntu. This is your return point if the install goes wrong.

  • Proxmox: select the VM, open Snapshots, click Take Snapshot.
  • VMware: VM menu, Snapshot, Take Snapshot.
  • VirtualBox: Machine Tools, Snapshots, Take.

Step 4: Run the Hermes Agent install script

Start the VM and run the official one-line installer from the Hermes installation docs:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Read any script before you pipe it to bash. You can download it first with curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o install.sh, read it, then run bash install.sh.

The script brings its own pinned Python and Node.js runtimes. It does not use your system Node.js. As of October 2026, pip, PyPI and Homebrew installs are not supported, so use the script. When it finishes, reload your shell and start the agent:

source ~/.bashrc
hermes

Here is where the files go:

  • Code: ~/.hermes/hermes-agent/
  • Launcher: ~/.local/bin/hermes
  • Data: ~/.hermes/, including config.yaml, .env (your API keys), memories, skills, sessions and state.db

Step 5: Choose a model and tools

Run the setup commands. You can do them one at a time or run the full wizard with hermes setup.

hermes model          # choose your provider and model
hermes tools          # choose which tools the agent may use
hermes config get     # check a setting

Start with few tools. Lock down the key file at the same time:

chmod 600 ~/.hermes/.env

Step 6: Run Hermes as a service

To keep the agent running after you log out, install the gateway as a systemd user service. Then turn on lingering so the service starts at boot without a login:

hermes gateway install
hermes gateway start
hermes gateway status
sudo loginctl enable-linger $USER

View the logs with journalctl --user -u hermes-gateway -f or hermes logs gateway -f.

Connect a chat app (optional)

The gateway can talk to you through Telegram, Discord, Slack, Signal, email and others. Run hermes gateway setup and follow the prompts. As of October 2026, the gateway denies every user who is not on an allowlist or paired. Keep it that way. Never set GATEWAY_ALLOW_ALL_USERS=true. Chat platforms need no inbound port on the VM.

Step 7: Snapshot the working agent

Once the agent answers you, shut down the VM and take a second snapshot, such as hermes-working. You now have two return points: a clean OS and a known-good agent.

Snapshots, backups and recovery

Snapshots and backups do different jobs. Use both.

ToolWhat it savesUse it when
VM snapshotThe whole VM: OS, agent code and dataBefore every update or big config change
hermes backupA zip of your Hermes data, including credentialsTo move the agent to a new VM, or keep a copy off the VM
hermes update --backupA full backup, then the updateEvery routine update

A safe update routine looks like this:

  1. Take a VM snapshot.
  2. Run hermes update --backup.
  3. Test the agent with one simple task.
  4. If it fails, revert to the snapshot. If it works, delete old snapshots after a few days.

To restore on a fresh VM, install Hermes, then run hermes import with the backup zip. The backup holds your API keys, so store it like a password.

Do not delete ~/.hermes/ to fix a broken install. The docs warn against it, because that folder holds all of your agent's state. Revert the snapshot instead.

Do not keep the data on a shared folder

Hermes stores state in an SQLite database in WAL mode. The Docker docs warn that bind mounts across a VM boundary (virtiofs, 9p and drvfs) can silently corrupt it. Keep ~/.hermes/ on the VM's own disk. Do not move it to a hypervisor shared folder to "save space".

Security hardening checklist

  • Run as a normal user. Never run the gateway as root.
  • Keep approvals on. Leave dangerous-command approval in smart or manual mode. Unattended and cron sessions deny by default.
  • Keep ports closed. The API server (port 8642) is off by default. The dashboard (port 9119) runs only when you start it with hermes dashboard --no-open, and it binds to 127.0.0.1. Reach it through an SSH tunnel: ssh -L 9119:localhost:9119 you@vm-address.
  • Use allowlists for every chat platform.
  • Give the VM no secrets it does not need. Do not copy your SSH keys or cloud credentials into it.
  • Consider a Docker terminal backend. Install Docker Engine in the VM, then set terminal.backend: docker. Shell and file tools then run in a container inside the VM. Note that Hermes skips command approval on this backend, because it treats the container as the boundary.

See the Hermes security guide for the full list.

Alternative: Hermes Agent in Docker inside the VM

If you prefer containers, the official image is nousresearch/hermes-agent, for amd64 and arm64. Install Docker in the VM from the Docker Engine docs for Ubuntu. Use this instead of the native install, not alongside it. Both use ~/.hermes, and two gateways must never share one data folder. Then run the first-time setup:

mkdir -p ~/.hermes
docker run -it --rm \
  -e HERMES_UID=$(id -u) -e HERMES_GID=$(id -g) \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Then start the gateway:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -e HERMES_UID=$(id -u) -e HERMES_GID=$(id -g) \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Two differences matter. First, hermes update refuses to run in Docker. You update by pulling a new image. Second, the dashboard runs only if you set HERMES_DASHBOARD=1, and inside the container it binds to 0.0.0.0. If you need it, publish it as -p 127.0.0.1:9119:9119 and use an SSH tunnel. If you use browser tools in Docker, add --shm-size=1g.

Troubleshooting

ProblemFix
hermes: command not foundRun source ~/.bashrc, or check that ~/.local/bin is in your PATH.
Installer exits with no message on minimal UbuntuRun sudo apt install libatomic1, then run the script again.
Installer hangs while it downloads a browserRun bash install.sh --skip-browser, or curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser. Add browser tools later, as the install docs describe.
"API key not set"Run hermes model and enter the key again.
Local Ollama model rejectedRaise the model's context to 64,000 tokens or more.
Config errors after an updateRun hermes config check, then hermes config migrate.
Anything elseRun hermes doctor. If it still fails, revert to your snapshot.

FAQ

Is Hermes Agent free?

The agent is open source under the MIT license. You pay for the model you connect, unless you run a local model. Check your provider's pricing page for current rates.

Can I install Hermes Agent with pip?

No. As of October 2026, the platform page lists pip and PyPI installs as unsupported. Use the official install script or the Docker image.

How much RAM does Hermes Agent need?

The official container figure is 1 GB minimum and 2 to 4 GB recommended. Browser tools need at least 2 GB. For a full Ubuntu VM, 4 GB is a comfortable start.

Does Hermes Agent work on Ubuntu 22.04?

It may work, because the docs say most glibc and systemd distributions are likely to work. As of October 2026, I found no official test of 22.04. Use 24.04 to stay on the tested path.

Is a VM safer than running Hermes on my laptop?

Yes. The agent runs commands on whatever machine it lives on. A VM limits that to a disposable system you can snapshot and revert. It is not perfect isolation, so still keep secrets out of the VM.

Can I run Hermes Agent in a VM on an Apple Silicon Mac?

As of October 2026, Hermes lists Linux on aarch64 as supported, so an ARM Ubuntu VM is a valid target. VMware Fusion Pro can run ARM Ubuntu. Hermes also runs natively on macOS, but then it has access to your Mac.

Related guides