Why run OpenClaw in Incus instead of Docker?

An Incus system container behaves like a small machine with persistent state, systemd, kernel-enforced resource limits, snapshots and live migration. That suits a long-running agent that accumulates workspace files, credentials and installed skills better than a disposable application container does.

Can I run Docker inside an Incus container?

Yes, but you must set security.nesting=true on the container. Without it, any OpenClaw skill or MCP server that shells out to Docker fails with a permissions error that looks like a bug in the skill rather than a container setting.

Can I migrate an existing LXD setup to Incus?

Yes. Incus ships an lxd-to-incus tool that converts an existing LXD installation in place, so containers do not have to be rebuilt by hand.

← Home

Guide

OpenClaw on Incus: Install in a System Container

Incus is the community fork of LXD, maintained under the Linux Containers project after Canonical moved LXD under its own governance in 2023. It runs system containers and real QEMU virtual machines from one CLI — and a system container is a much more natural home for a long-running agent than a Docker process container is.

Why Incus Instead of Docker?

Docker gives you an application container: one process, an image layer, and a filesystem that is meant to be thrown away. That is a good fit for stateless services and an awkward one for an agent that accumulates a workspace, credentials, installed skills, and cron state over months.

An Incus system container behaves like a small machine. It boots an init system, you SSH into it, you install packages the normal way, and the state persists because persisting is the default rather than a volume you remembered to mount. Concretely, that buys you:

Snapshots — capture the whole container before an upgrade and roll back in seconds if the new version misbehaves
Real resource limits — CPU, memory and disk quotas per container, enforced by the kernel
Ordinary operations — systemd units, log rotation and cron work exactly as they do on a VM, with no image rebuild to change anything
Live migration — move a running container between hosts

The cost is that you are administering a small Linux box. If you want none of that, managed hosting removes the question entirely — see OpenClaw hosting.

Install Incus

Incus 7.0 LTS shipped on 1 May 2026 and is packaged in Debian stable, Fedora, openSUSE and NixOS. On Ubuntu the recommended route is the Zabbly stable repository, which tracks releases more closely than the distro archive:

# Ubuntu 22.04 / 24.04 / 26.04
sudo mkdir -p /etc/apt/keyrings
sudo curl -fsSL https://pkgs.zabbly.com/key.asc -o /etc/apt/keyrings/zabbly.asc
sudo sh -c 'cat <<EOF > /etc/apt/sources.list.d/zabbly-incus-stable.sources
Enabled: yes
Types: deb
URIs: https://pkgs.zabbly.com/incus/stable
Suites: $(. /etc/os-release && echo ${VERSION_CODENAME})
Components: main
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/zabbly.asc
EOF'

sudo apt update && sudo apt install -y incus
sudo usermod -aG incus-admin "$USER"   # log out and back in

Then initialise the daemon once:

incus admin init --minimal

Already running LXD? Incus ships lxd-to-incus, which converts an existing LXD installation in place rather than making you rebuild containers by hand.

Create the Container

Give the agent its own container with sensible limits. Nesting is enabled here because OpenClaw skills and MCP servers frequently want Docker available inside:

incus launch images:ubuntu/24.04 openclaw \
  -c limits.cpu=2 \
  -c limits.memory=4GiB \
  -c security.nesting=true

incus exec openclaw -- bash

security.nesting=true is what allows a container runtime to run inside the container. Without it, any skill that shells out to Docker fails with a permissions error that reads like a bug in the skill.

Install OpenClaw Inside

From the shell you just opened:

apt update && apt install -y curl git
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs

npm install -g openclaw
openclaw onboard

The onboarding flow walks through model provider, API key and channel setup. For the config file details see the full install guide, which applies unchanged here — from OpenClaw's point of view an Incus system container is just a Linux host.

Keep the Gateway Running

Because an Incus system container runs a real init system, OpenClaw's own daemon installer works exactly as it does on a VM. Use it rather than hand-writing a unit file:

# system-wide unit, starts on boot
openclaw onboard --install-daemon --system

systemctl status openclaw

This registers OpenClaw with systemd, starts it immediately and enables it on boot. See the --install-daemon reference for the per-user variant and the --port flag. Do not also run the gateway under tmux, screen or PM2 — those conflict with the daemon.

The container itself should also come back after a host reboot:

incus config set openclaw boot.autostart=true

Snapshot Before Every Upgrade

This is the reason to use Incus in the first place. Take a snapshot before touching anything, and rollback becomes a ten-second operation instead of an incident:

incus snapshot create openclaw pre-upgrade
npm install -g openclaw@latest   # inside the container

# if it goes wrong:
incus snapshot restore openclaw pre-upgrade

A snapshot captures the whole userland — the agent workspace, installed skills, credentials and config together — so a restore returns a coherent state rather than a mismatched half-upgrade.

Reaching the Gateway From Outside

Containers sit on Incus's bridge by default, so the gateway is not reachable from the host network until you forward the port:

incus config device add openclaw gateway proxy \
  listen=tcp:0.0.0.0:18789 \
  connect=tcp:127.0.0.1:18789

Do not expose that port to the internet directly. Put a reverse proxy with TLS in front of it, and read the security guide before opening anything — an exposed agent gateway is an exposed shell.

Troubleshooting

Docker fails inside the container

Almost always missing nesting. Check with incus config get openclaw security.nesting, set it to true, and restart the container.

The agent dies overnight

If the memory limit is too tight, the kernel OOM-kills the process and systemd restarts it in a loop. Check incus info openclaw for memory usage and raise limits.memory. Browser-driving skills in particular need considerably more headroom than a text-only agent.

Nothing starts after a host reboot

Set boot.autostart=true as above. It is not the default, and it is the most common way an Incus-hosted agent silently disappears.

Incus or Managed Hosting?

Incus is a genuinely good answer if you already run a homelab or a server you maintain, and you want snapshots and real isolation without full VM overhead. You are still responsible for the host, kernel updates, backups, TLS and uptime.

If what you actually want is the agent rather than the infrastructure, OpenClaw Launch deploys a managed instance in about 30 seconds with updates and backups handled. Compare the trade-offs in deploying OpenClaw on a VPS.

What's Next?

Full install guide
Deploy OpenClaw on a VPS
OpenClaw with Docker
OpenClaw on Ubuntu
Managed hosting — skip the infrastructure entirely