Immutable tags · Compose discipline · Smoke before traffic · Gateway-ready rollback
Solo operators and small teams running OpenClaw on a VPS often wake up to surprise upgrades because :latest pulled a new Gateway build overnight. This article explains why floating tags break reproducibility, how to pin semver or digest in Compose and Kubernetes, what to back up before changing images, how to run dual-instance smoke in a quiet window, and a rollback shell shape that restores the previous tag and re-checks health and channels. Cross-read with sustainable upgrades, VPS Docker install, Exit 137 and WASM window, and Gateway doctor triage.
:latest fights production OpenClawFloating tags hide three kinds of drift: the Gateway binary surface your Skills assumed, the plugin or channel schema your callbacks relied on, and the container base libraries around Node. Pulling “whatever is newest” turns incidents into guessing games because two hosts rarely fetch identical layers at different times. That breaks postmortems and erodes trust with anyone wiring IM or webhooks into your VPS.
| Surface | What moves under :latest | Symptom you feel first |
|---|---|---|
| Gateway API | CLI flags, config schema, Control UI routes | Skills fail validation after an unplanned restart |
| Channels | Webhook handshake timing, Discord intents defaults | Silent message drops until someone notices backlog |
| Runtime stack | Node patch level, libc compatibility | First-boot WASM or native deps spike CPU or OOM |
Production OpenClaw belongs to images you can name twice: once in Git and once on the host—same characters, same digest optional.
Note: zero-downtime cluster moves belong with DR and zero-downtime upgrades; this page targets single or dual Compose stacks on a VPS.
Pick one immutable reference per environment: either a release tag you tested (v2026.4.2) or a digest if you need byte-level sameness across regions. Store that string beside your compose file and mirror it into your incident tickets.
services:
openclaw:
image: ghcr.io/openclaw/openclaw:v2026.4.2
pull_policy: missing
pull_policy: missing or pin digest when automation must not mutate running containers.Warning: editing only openclaw.json while the image silently advances still counts as an unmanaged upgrade—pin both config revision and image reference in the same change ticket.
Before any docker compose pull, freeze scope so rollback knows what “good” meant.
Config volume: snapshot ~/.openclaw or the mounted path; capture file list checksum if your backup tool supports it.
Workspace: note Skill directories and any secrets outside the volume that compose maps via env_file.
Channels: export webhook URLs and verify inbound reachability windows align with maintenance messaging.
Smoke list: pick two Skills and one channel send-receive pair that must pass before routing production traffic.
Resources: confirm memory headroom for first-run compile spikes described in the Exit 137 article.
Run the candidate image as a second project name or alternate compose file on non-production ports. Shift only after smoke passes.
| Signal | Where to look | Pass criteria |
|---|---|---|
| Gateway health | curl loopback health endpoint | HTTP 200 stable for several probes |
| Channels status | Gateway logs or CLI status | No reconnect storm; callbacks acknowledged |
| Skill audit | Skill runner output | No new deny rules versus staging expectations |
| Control UI | Browser against pinned origin | No non-loopback mismatch after proxy rules |
Keep the promotion window short; long overlaps multiply drift between databases or queues your Gateway touches.
Treat rollback as a rehearsed script, not improvisation. Replace the image reference with your last known-good tag, pull explicitly, recreate containers, then prove health before announcing recovery.
export OPENCLAW_IMAGE_TAG="v2026.4.1" docker compose pull openclaw docker compose up -d --force-recreate openclaw curl -sf http://127.0.0.1:18789/health
When your VPS stack sits beside macOS-dependent workloads, separate Gateway uptime from compile pools so rollback debates stay scoped. For dedicated remote Mac capacity with clearer boundaries than home hardware, review Mac Mini rental pricing and cloud ordering alongside this Gateway discipline.
The sustainable upgrades guide focuses on channels, update cadence, and backups across environments. This article narrows to Docker image pinning, staging smoke, and rollback commands for VPS operators.
Use tested semver tags for most teams; move to digests when regulators or multi-region parity demand identical bytes. Either way, write the reference next to compose in Git.
First boot and sizing live in OpenClaw v2026.4 VPS Docker install; memory spikes during upgrades overlap with Exit 137 and WASM window guidance.