Clawdbot Updates Management

Enhanced update management for Clawdbot with safety controls, version tracking, and rollback capability.

Quick Start

Check for updates:

scripts/check-updates.sh

Update with backup:

scripts/backup-config.sh
scripts/apply-update.sh

Rollback if needed:

scripts/rollback.sh

Decision Tree

User requests update
├─ Step 1: Check current vs latest
│  └─ Run check-updates.sh
│     ├─ Already latest → Inform user, done
│     └─ Update available → Continue to Step 2
│
├─ Step 2: Show what's new
│  └─ Display:
│     ├─ Version comparison (current → latest)
│     ├─ Changelog/release notes
│     └─ Breaking changes warnings
│     └─ Ask: Proceed? → No → Done
│
├─ Step 3: Backup current state
│  └─ Run backup-config.sh
│     ├─ Backs up config.yaml
│     ├─ Records current version
│     ├─ Creates timestamped backup
│     └─ On failure → Abort update
│
├─ Step 4: Apply update
│  └─ Run apply-update.sh
│     ├─ Pulls latest code
│     ├─ Installs dependencies
│     ├─ Validates config
│     ├─ Restarts gateway
│     └─ On failure → Offer rollback
│
└─ Step 5: Verify
   └─ Check gateway status
      ├─ Success → Cleanup old backups
      └─ Failure → Run rollback.sh

Scripts

check-updates.sh

Compares current vs latest version without making changes.

Output:

• Current version
• Latest available version
• Changelog summary
• Breaking changes flag

Exit codes:

• 0: Update available
• 1: Already latest
• 2: Error checking

backup-config.sh

Creates timestamped backup before updates.

What's backed up:

• config.yaml
• Current git commit hash
• Package.json dependencies
• Timestamp and version metadata

Backup location: ~/.clawdbot-backups/YYYY-MM-DD-HHMMSS/

Exit codes:

• 0: Backup successful
• 1: Backup failed

apply-update.sh

Applies the update with validation.

Process:

1. Verify backup exists
2. Git pull latest changes
3. npm install dependencies
4. Validate config.yaml
5. Restart gateway via gateway tool

Exit codes:

• 0: Update successful
• 1: Update failed (safe to rollback)

rollback.sh

Restores from most recent backup.

Process:

1. Find latest backup
2. Restore config.yaml
3. Git checkout previous commit
4. Restore dependencies
5. Restart gateway

Exit codes:

• 0: Rollback successful
• 1: Rollback failed (manual intervention needed)

Multi-Gateway Sync

When managing multiple gateways (ada-gateway, Pi, etc.):

1. Test on one gateway first (typically ada-gateway)
2. Verify stability for 24 hours
3. Sync to other gateways using the same scripts via nodes_run or SSH

Example sync to Pi:

# After successful update on ada-gateway
nodes run --node pi --command "cd ~/clawdbot && ./skills/clawdbot-updates/scripts/apply-update.sh"

Mac Node Update

The Mac (MascotM3) runs two Clawdbot components that need separate updates:

1. CLI + Browser Relay

# SSH to Mac and update
ssh henrymascot@100.86.150.96 "export PATH=\"/opt/homebrew/bin:\$PATH\" && npm update -g clawdbot"

2. Chrome Extension (after CLI update)

# Reinstall extension files
ssh henrymascot@100.86.150.96 "export PATH=\"/opt/homebrew/bin:\$PATH\" && clawdbot browser extension install"

Then manually in Chrome:

• Go to chrome://extensions
• Find "Clawdbot Browser Relay"
• Click Reload

3. Restart Browser Serve (if running)

# Kill and restart browser serve
ssh henrymascot@100.86.150.96 "pkill -f 'clawdbot browser serve'; export PATH=\"/opt/homebrew/bin:\$PATH\" && nohup clawdbot browser serve --bind 127.0.0.1 --port 18791 > ~/.clawdbot-browser-serve.log 2>&1 &"

4. Mac App (Node capabilities)

The native Mac app (com.clawdbot.mac.debug) updates separately - check for new releases or auto-update if supported.

Full Mac Update Command

# One-liner for CLI + extension + browser serve restart
ssh henrymascot@100.86.150.96 "export PATH=\"/opt/homebrew/bin:\$PATH\" && npm update -g clawdbot && clawdbot browser extension install && pkill -f 'clawdbot browser serve' || true && nohup clawdbot browser serve --bind 127.0.0.1 --port 18791 > ~/.clawdbot-browser-serve.log 2>&1 &"

Note: After running this, manually reload the extension in Chrome (chrome://extensions → Reload).

Risk Assessment

Before updating, evaluate:

Low risk:

• Patch version bump (1.2.3 → 1.2.4)
• Bug fixes only
• No config changes

Medium risk:

• Minor version bump (1.2.0 → 1.3.0)
• New features added
• Optional config additions

High risk:

• Major version bump (1.0.0 → 2.0.0)
• Breaking changes noted
• Config format changes
• Deprecations

Always backup before medium/high risk updates.

Config Validation

After update, verify:

• Config schema matches new version
• All required fields present
• Deprecated fields migrated
• Gateway restarts successfully

Use gateway action=config.schema to check schema compatibility.

Troubleshooting

Gateway won't restart:

1. Check logs: journalctl -u clawdbot -n 50
2. Validate config: gateway action=config.get
3. Rollback if needed: scripts/rollback.sh

Update fails mid-process:

1. Don't panic - backup exists
2. Run rollback.sh
3. Check logs for root cause
4. Report issue before retrying

Rollback fails:

1. Backup still exists at ~/.clawdbot-backups/
2. Manually restore config: cp backup/config.yaml ~/clawdbot/config.yaml
3. Manually restore code: git reset --hard <commit-hash>
4. Restart: gateway action=restart

Best Practices

1. Always backup before updating - Automated in scripts
2. Read changelog first - Check for breaking changes
3. Test on non-production first - Use ada-gateway before Pi
4. Update during low-usage times - Avoid peak hours
5. Keep multiple backups - Don't delete immediately
6. Monitor after update - Watch for 24 hours
7. Document issues - Help improve future updates

Maintenance

Cleanup old backups:

# Keep last 5 backups, delete older
ls -t ~/.clawdbot-backups/ | tail -n +6 | xargs -I {} rm -rf ~/.clawdbot-backups/{}

Check backup space:

du -sh ~/.clawdbot-backups/