Feature: Workspace persistence via R2 backup/restore

[raphaeltm]

Summary

Currently workspaces are ephemeral - all data is lost when VMs terminate (either manually or via idle timeout). Users must commit and push all changes before the workspace shuts down, which is a poor UX and risks data loss.

Prior Research

This was researched in research/dns-security-persistence-plan.md (Phase 3). The recommended approach:

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Cloudflare Workers KV                                      │
│  Key: workspace:{workspace-id}:encryption-key               │
│  Value: AES-256 key (encrypted with master key from env)    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Cloudflare R2                                              │
│  Bucket: workspaces                                         │
│  Object: {workspace-id}/workspace.tar.gz.enc                │
└─────────────────────────────────────────────────────────────┘

Key Design Decisions

1. Encryption: Per-workspace AES-256 key, stored encrypted in KV
2. Storage: Cloudflare R2 (no egress fees, native to ecosystem)
3. Claude Auth: Set CLAUDE_CONFIG_DIR=/workspaces/.claude so credentials persist with backup

Backup Flow (on shutdown/idle)

# 1. Tar workspace
tar -czf /tmp/workspace.tar.gz -C /workspaces .

# 2. Encrypt with workspace key
openssl enc -aes-256-cbc -salt -pbkdf2 \
  -in /tmp/workspace.tar.gz \
  -out /tmp/workspace.tar.gz.enc \
  -pass env:WORKSPACE_KEY

# 3. Upload to R2
aws s3 cp /tmp/workspace.tar.gz.enc \
  s3://workspaces/${WORKSPACE_ID}/workspace.tar.gz.enc \
  --endpoint-url ${R2_ENDPOINT}

Restore Flow (on startup)

# 1. Download from R2 (if exists)
aws s3 cp s3://workspaces/${WORKSPACE_ID}/workspace.tar.gz.enc \
  /tmp/workspace.tar.gz.enc --endpoint-url ${R2_ENDPOINT} || true

# 2. Decrypt and extract
if [ -f /tmp/workspace.tar.gz.enc ]; then
  openssl enc -aes-256-cbc -d -pbkdf2 \
    -in /tmp/workspace.tar.gz.enc \
    -out /tmp/workspace.tar.gz \
    -pass env:WORKSPACE_KEY
  tar -xzf /tmp/workspace.tar.gz -C /workspaces
fi

Tasks

• Create R2 bucket for workspace backups
• Add workspace encryption key generation to workspace creation flow
• Store encryption keys in KV (encrypted with master key)
• Update cloud-init to include restore logic on startup
• Add backup trigger to idle detection (before self-destruct)
• Add manual backup trigger via agent API
• Update workspace restart flow to restore from backup
• Add key rotation support
• Consider periodic backups (not just on shutdown)
• Add UI indicator for backup status

UX Considerations

• Restart behavior: Stopped workspaces can be restarted and will restore their state
• Delete behavior: Deleting a workspace should also delete its R2 backup
• Backup timing: Backup before idle shutdown, not after (risk of data loss)
• Large workspaces: May need chunked upload or size limits

Priority

Post-MVP enhancement. Current ephemeral design is intentional for MVP simplicity, but this is high-value for real usage.

References

• research/dns-security-persistence-plan.md - Full architecture details
• specs/001-mvp/spec.md - Lists this as out of scope for MVP

Labels

enhancement, feature