Safe updates

Overview

Treat these as two separate upgrade tracks:

1. Clawforce control-plane updates
2. OpenClaw runtime updates inside customer instances

Do not roll both out in the same maintenance window.

Core rule

For production environments, do not depend on mutable latest tags.

Use:

• explicit image tags such as clawforceone/clawforce:1.4.2
• explicit agent image tags such as clawforceone/agent-chromium:1.4.2-openclaw-<version>
• or digest-pinned images

Keep the previous known-good image reference so rollback is one change, not a rebuild.

Clawforce control-plane updates

Before upgrading Clawforce:

1. Record the current image tag and deployment config.
2. Take a host-level snapshot of CLAWFORCE_DATA_PATH or the PVC that backs /app/data.
3. Upgrade to one explicit target image tag.
4. Verify /health, login, instances, and Backups.

The repo includes a helper script for the control-plane snapshot itself:

# Installer-managed Docker
scripts/control-plane-state.sh snapshot docker \
  --data-dir ~/.clawforce/data \
  --archive ./snapshots/clawforce-docker-$(date -u +%Y%m%dT%H%M%SZ).tar.gz

# Docker Compose
scripts/control-plane-state.sh snapshot docker \
  --volume clawforce-data \
  --archive ./snapshots/clawforce-compose-$(date -u +%Y%m%dT%H%M%SZ).tar.gz

# Helm / Kubernetes
scripts/control-plane-state.sh snapshot kubernetes \
  --namespace clawforce \
  --release clawforce \
  --archive ./snapshots/clawforce-k8s-$(date -u +%Y%m%dT%H%M%SZ).tar.gz

Rollback order:

1. redeploy the previous Clawforce image tag
2. if needed, restore the pre-upgrade snapshot of CLAWFORCE_DATA_PATH

Restore examples:

scripts/control-plane-state.sh restore docker \
  --data-dir ~/.clawforce/data \
  --archive ./snapshots/clawforce-docker-20260421T120000Z.tar.gz \
  --yes

scripts/control-plane-state.sh restore kubernetes \
  --namespace clawforce \
  --release clawforce \
  --archive ./snapshots/clawforce-k8s-20260421T120000Z.tar.gz \
  --yes

The restore path takes a fresh pre-restore backup by default before it wipes the current control-plane data.

The Clawforce backup UI does not back up the control-plane database or SSH keys. That snapshot is required for a full rollback story.

OpenClaw runtime updates

Upstream OpenClaw changes frequently. Production customers should adopt those changes through tested agent image releases, not by running package upgrades directly inside long-lived instances.

Recommended flow:

1. Create an instance backup from Backups.
2. Upgrade one canary instance to the new agent image tag.
3. Validate a representative workflow.
4. Update the default container image for new instances.
5. Roll the rest of the fleet in waves.

Rollback order:

1. point the instance back to the previous agent image tag
2. if the runtime also changed important files, restore the pre-upgrade instance backup

Backup guidance

Use the built-in backup system for instance filesystem state:

• home directory
• OpenClaw config
• packages and files you explicitly include

Use host or storage snapshots for control-plane state:

• clawforce.db
• SSH keys
• backup metadata and archives

Production checklist

• no latest in production
• canary before fleet rollout
• control-plane snapshot before Clawforce upgrade
• instance backup before OpenClaw runtime upgrade
• previous image tag ready before rollout starts