Skip to main content
Shared runtime steps for VM-based Docker installs such as GCP, Hetzner, and similar VPS providers.

​
Bake required binaries into the image

Installing binaries inside a running container is a trap: anything installed at runtime is lost on restart. Bake every external binary a skill needs into the image at build time. The examples below cover three binaries only, alphabetically:
  • gog (from gogcli) for Gmail access
  • goplaces for Google Places
  • wacli for WhatsApp
These are examples, not a complete list. Install as many binaries as your skills need using the same pattern. When you add a skill that needs a new binary later:
  1. Update the Dockerfile.
  2. Rebuild the image.
  3. Restart the containers.
Example Dockerfile 
FROM node:24-bookworm

RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*

# Example binary 1: Gmail CLI (gogcli — installs as `gog`)
# Copy the current Linux asset URL from https://github.com/steipete/gogcli/releases
RUN curl -L https://github.com/steipete/gogcli/releases/latest/download/gogcli_linux_amd64.tar.gz \
  | tar -xzO gog > /usr/local/bin/gog; \
  chmod +x /usr/local/bin/gog

# Example binary 2: Google Places CLI
# Copy the current Linux asset URL from https://github.com/steipete/goplaces/releases
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_linux_amd64.tar.gz \
  | tar -xzO goplaces > /usr/local/bin/goplaces; \
  chmod +x /usr/local/bin/goplaces

# Example binary 3: WhatsApp CLI
# Copy the current Linux asset URL from https://github.com/steipete/wacli/releases
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli-linux-amd64.tar.gz \
  | tar -xzO wacli > /usr/local/bin/wacli; \
  chmod +x /usr/local/bin/wacli

# Add more binaries below using the same pattern

WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN corepack enable
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]
The URLs above are examples. For ARM-based VMs, choose the arm64 assets. For reproducible builds, pin versioned release URLs.

​
Build and launch

docker compose build
docker compose up -d openclaw-gateway
If the build fails with Killed or exit code 137 during pnpm install --frozen-lockfile, the VM is out of memory. Use a larger machine class before retrying. Verify binaries: 
docker compose exec openclaw-gateway which gog
docker compose exec openclaw-gateway which goplaces
docker compose exec openclaw-gateway which wacli
Expected output: 
/usr/local/bin/gog
/usr/local/bin/goplaces
/usr/local/bin/wacli
Verify the gateway is up: 
docker compose logs -f openclaw-gateway
curl -fsS http://127.0.0.1:18789/healthz
/healthz returning a 200 response confirms the gateway process is listening and healthy; the built-in image HEALTHCHECK polls the same endpoint.

​
What persists where

OpenClaw runs in Docker, but Docker is not the source of truth. All long-lived state must survive restarts, rebuilds, and reboots.
ComponentLocationPersistence mechanismNotes
Gateway config/home/node/.openclaw/Host volume mountIncludes openclaw.json
Channel/provider creds/home/node/.openclaw/credentials/Host volume mountChannel and provider credential material
Model auth profiles/home/node/.openclaw/agents/Host volume mountagents/<agentId>/agent/auth-profiles.json (OAuth, API keys)
Legacy OAuth key file/home/node/.config/openclaw/Host volume mountRead-only compat for pre-migration OAuth sidecars; openclaw doctor --fix migrates these into auth-profiles.json
Skill configs/home/node/.openclaw/skills/Host volume mountSkill-level state
Agent workspace/home/node/.openclaw/workspace/Host volume mountCode and agent artifacts
WhatsApp session/home/node/.openclaw/Host volume mountPreserves QR login
Gmail keyring/home/node/.openclaw/Host volume + passwordRequires GOG_KEYRING_PASSWORD
Plugin packages/home/node/.openclaw/npm, /home/node/.openclaw/gitHost volume mountDownloadable plugin package roots
External binaries/usr/local/bin/Docker imageMust be baked at build time
Node runtimeContainer filesystemDocker imageRebuilt every image build
OS packagesContainer filesystemDocker imageDo not install at runtime
Docker containerEphemeralRestartableSafe to destroy

​
Updates

To update OpenClaw on the VM: 
git pull
docker compose build
docker compose up -d