Container Management Skill

# Container Management Skill

You are an AI assistant running inside a Cloudflare Sandbox container. This document explains how to manage your workspace persistence and R2 storage.

## Getting These Tools

### First Time Setup
If the tools don't exist yet, clone them:
```bash
# Check if tools exist
if [ ! -d "/openclaw-container-tools" ]; then
    cd /
    git clone https://github.com/jerryfane/openclaw-container-tools.git
    chmod +x /openclaw-container-tools/scripts/*.sh
    echo "Tools installed successfully!"
else
    echo "Tools already exist"
fi
```

### Updating Tools
To get the latest version:
```bash
cd /openclaw-container-tools
git pull origin main
chmod +x scripts/*.sh
echo "Tools updated!"
```

### Quick Check
```bash
# Verify tools are available
ls -la /openclaw-container-tools/scripts/
```

## Core Understanding

You're running in a container that can restart at any time. To preserve your work:
- Your OpenClaw workspace at `/root/clawd/` should be synced to R2 storage
- R2 is mounted at `/data/moltbot/`
- The sync scripts are in `/openclaw-container-tools/scripts/`

**Note**: The sync script automatically detects your workspace location:
- Primary: `/root/clawd/` (OpenClaw/Clawdbot standard location)
- Fallback: `/workspace/` (if it exists)
- Override: Set `WORKSPACE_DIR` environment variable for custom path

## Available Tools

### 1. Workspace Sync Script
**Path**: `/openclaw-container-tools/scripts/sync-workspace-to-r2.sh`

**Purpose**: Backs up your entire OpenClaw workspace (`/root/clawd/`) to R2, excluding large/unnecessary files like `node_modules`, `.git`, `__pycache__`, etc.

**How to use**:
```bash
# Regular sync
/openclaw-container-tools/scripts/sync-workspace-to-r2.sh

# Test mode (see what would sync without doing it)
DRY_RUN=true /openclaw-container-tools/scripts/sync-workspace-to-r2.sh

# DANGEROUS: Enable deletion mode (removes files from R2 that don't exist locally)
# Only use this if you really want to clean up R2!
DELETE_MODE=true /openclaw-container-tools/scripts/sync-workspace-to-r2.sh
```

**What it does**:
- Syncs `/root/clawd/` → `/data/moltbot/workspace/`
- Skips node_modules, .git, build outputs, virtual envs
- **NEVER deletes files from R2** (default behavior for safety)
- Shows progress and statistics

**Important**: Files are only ADDED/UPDATED in R2, never deleted. This protects against data loss on container restart.

### 2. Startup Script (Reference)
**Path**: `/openclaw-container-tools/scripts/start-moltbot.sh`

This runs automatically when the container starts. It:
- Restores your config from R2 if available
- Sets up the gateway
- You don't run this manually

## Checking R2 Status

### Is R2 Mounted?
```bash
# Check if R2 mount exists
ls -la /data/moltbot/

# Check mount status
mount | grep "/data/moltbot"

# See what's in R2
ls -la /data/moltbot/workspace/
```

### Are R2 Credentials Set?
```bash
# Check environment variables
env | grep -E "R2_|CF_ACCOUNT"
```

If missing, R2 won't work. The credentials need to be:
- `R2_ACCESS_KEY_ID`
- `R2_SECRET_ACCESS_KEY`
- `CF_ACCOUNT_ID`

## Setting Up Automated Sync (Heartbeat)

### Option 1: Cron Job (Recommended)
```bash
# Add to crontab (syncs every hour)
(crontab -l 2>/dev/null; echo "0 * * * * /openclaw-container-tools/scripts/sync-workspace-to-r2.sh >> /var/log/workspace-sync.log 2>&1") | crontab -

# Or every 30 minutes
(crontab -l 2>/dev/null; echo "*/30 * * * * /openclaw-container-tools/scripts/sync-workspace-to-r2.sh >> /var/log/workspace-sync.log 2>&1") | crontab -

# Check if cron is set
crontab -l
```

### Option 2: Background Loop
```bash
# Run sync every 30 minutes in background
nohup bash -c 'while true; do /openclaw-container-tools/scripts/sync-workspace-to-r2.sh; sleep 1800; done' > /var/log/sync-loop.log 2>&1 &

# Check if running
ps aux | grep sync-workspace
```

### Option 3: Manual Trigger
Just run the sync when you've made important changes:
```bash
/openclaw-container-tools/scripts/sync-workspace-to-r2.sh
```

## Restoring From R2

If you need to restore workspace from R2:
```bash
# Check what's in R2
ls -la /data/moltbot/workspace/

# Restore everything to OpenClaw workspace (CAREFUL - overwrites local)
rsync -av /data/moltbot/workspace/ /root/clawd/

# Restore specific directory
rsync -av /data/moltbot/workspace/myproject/ /root/clawd/myproject/

# Custom workspace location
WORKSPACE_DIR=/custom/path rsync -av /data/moltbot/workspace/ $WORKSPACE_DIR/
```

## Troubleshooting

### "R2 mount point does not exist"
R2 isn't mounted. Check:
1. Are credentials set? `env | grep R2_`
2. Is container properly configured?
3. Try: `mount | grep s3fs`

### "Workspace size exceeds maximum"
The script has a 10GB safety limit. If needed:
1. Clean up unnecessary files
2. Or edit the script: `MAX_SIZE_GB=20`

### Sync is slow
- First sync is always slow (copies everything)
- Later syncs are incremental (fast)
- Large files slow it down

### Nothing to sync
Check if you have files:
```bash
ls -la /root/clawd/
find /root/clawd -type f | head -20

# Or check detected workspace
/openclaw-container-tools/scripts/sync-workspace-to-r2.sh | head -5
```

### Check sync history
```bash
# Last sync time
cat /data/moltbot/workspace/.last-sync

# Sync completed marker
cat /data/moltbot/workspace/.sync-complete
```

## Important Notes

1. **The sync script ignores**:
   - node_modules (npm packages)
   - .git (version control)
   - __pycache__, venv (Python stuff)
   - dist, build (compilation outputs)
   - Large archives (.zip, .tar.gz)

2. **No automatic deletion**: Files are NEVER deleted from R2 by default (safety feature)
   - Protects against data loss on container restart
   - Use `DELETE_MODE=true` only when you want to clean up R2

3. **Safety**: Script won't sync more than 10GB by default

4. **Persistence**: After container restart, restore your workspace from R2

5. **Workspace Detection**: Script auto-detects `/root/clawd/` (OpenClaw) or `/workspace/`

## Quick Commands Reference

```bash
# Sync now (safe - only adds/updates, never deletes)
/openclaw-container-tools/scripts/sync-workspace-to-r2.sh

# Test sync (dry run)
DRY_RUN=true /openclaw-container-tools/scripts/sync-workspace-to-r2.sh

# Clean up R2 (DANGEROUS - removes files not in local)
DELETE_MODE=true /openclaw-container-tools/scripts/sync-workspace-to-r2.sh

# Set up hourly sync
(crontab -l 2>/dev/null; echo "0 * * * * /openclaw-container-tools/scripts/sync-workspace-to-r2.sh") | crontab -

# Check R2 contents
ls -la /data/moltbot/workspace/

# Restore from R2
rsync -av /data/moltbot/workspace/ /root/clawd/

# Check last sync
cat /data/moltbot/workspace/.last-sync
```

## Your Workflow

When working on projects:
1. Make changes in `/root/clawd/` (your OpenClaw workspace)
2. Run sync script periodically (or set up cron)
3. Your work accumulates in R2 (never deleted automatically)
4. After container restart, restore from R2

**Safety First**: The sync script will NEVER delete files from R2 unless you explicitly use `DELETE_MODE=true`. This means:
- On container restart with empty workspace, syncing won't delete R2 data
- R2 acts as a cumulative backup of all your work
- Old files stay in R2 even if deleted locally (unless you explicitly clean)

Remember: Container can restart anytime. Sync important work frequently!