claude-os/docs/guides/BACKUP_RESTORE_GUIDE.md

Claude OS Backup & Restore Guide

This guide explains how to safely backup and restore your Claude OS installation, perfect for testing fresh installations without losing data.

Quick Start

1. Backup Your Current Setup

./scripts/backup_claude_os.sh

This creates a timestamped backup in backups/backup_YYYYMMDD_HHMMSS/ containing:

• SQLite database (all projects, knowledge bases, documents)
• Configuration files (.env, JSON configs)
• Uploaded documents
• Recent log files
• Symlink information

Output example:

Backup location: /Users/iamanmp/Projects/claude-os/backups/backup_20251101_135211
Backup size: 125M
Backup timestamp: 20251101_135211

To restore this backup later:
  ./scripts/restore_claude_os.sh 20251101_135211

2. Test Fresh Installation

Now you can safely test the installation process:

# Option 1: Test quick install
./install.sh

# Option 2: Test full setup
./setup.sh

3. Restore Your Data

If you need to restore your backup:

./scripts/restore_claude_os.sh 20251101_135211

Replace 20251101_135211 with your actual backup timestamp.

---

What Gets Backed Up?

Critical Data (Automatically Backed Up)

1. SQLite Database (data/claude-os.db)

   • All projects
   • All knowledge bases
   • All documents and embeddings
   • Search history
   • Typically 100-200MB

2. Configuration Files

   • .env - Environment variables (Ollama settings, API keys, etc.)
   • claude-os-config.json - Project configuration
   • claude-os-state.json - Current session state
   • claude-os-triggers.json - Custom trigger phrases

3. Uploaded Documents (data/uploads/)

   • Any files uploaded through the UI

4. Recent Logs (logs/)

   • Recent log files (< 10MB each)
   • Useful for debugging

5. Symlink Information

   • Record of ~/.claude/commands/ symlinks
   • Record of ~/.claude/skills/ symlinks
   • For reference only (recreated by install.sh)

What's NOT Backed Up (No Need)

• node_modules/ - Reinstalled from package.json
• venv/ - Recreated during installation
• Python packages - Reinstalled from requirements.txt
• Ollama models - Remain in system location
• Templates - Already in git repository
• Large log files (> 10MB)

---

Detailed Usage

Backup Command

./scripts/backup_claude_os.sh

What it does:

1. Creates timestamped backup directory
2. Copies all critical files
3. Records symlink state
4. Creates manifest file
5. Shows backup summary

No arguments needed - timestamps are automatic.

Restore Command

./scripts/restore_claude_os.sh <timestamp>

Examples:

# Restore specific backup
./scripts/restore_claude_os.sh 20251101_135211

# List available backups
./scripts/restore_claude_os.sh

What it does:

1. Verifies backup exists
2. Shows manifest
3. Asks for confirmation (press Enter to continue)
4. Restores all files
5. Provides next steps

⚠️ WARNING: Restore will overwrite your current data! Make a new backup first if you want to keep current state.

---

Testing Fresh Installations

Recommended Workflow

1. Backup first:

   ./scripts/backup_claude_os.sh
   

2. Stop all services:

   ./stop_all_services.sh
   

3. Clean up (optional but thorough):

   # Remove symlinks (will be recreated)
   rm ~/.claude/commands/claude-os-*.md
   rm ~/.claude/skills/memory
   rm ~/.claude/skills/initialize-project
   rm ~/.claude/skills/remember-this
   
   # Remove virtual environment
   rm -rf venv venv_py312 venv_py313
   

4. Test installation:

   # Test quick install
   ./install.sh
   
   # OR test full setup
   ./setup.sh
   

5. Verify it works:

   # Start services
   ./start.sh
   
   # Check health
   curl http://localhost:8051/health
   
   # Check UI
   open http://localhost:5173
   

6. If something goes wrong, restore:

   ./scripts/restore_claude_os.sh 20251101_135211
   ./start.sh
   

---

Common Scenarios

Scenario 1: Test install.sh for a user report

# 1. Backup everything
./scripts/backup_claude_os.sh

# 2. Clean installation (keep data, test scripts)
rm -rf venv
rm ~/.claude/commands/claude-os-*.md
rm ~/.claude/skills/{memory,initialize-project,remember-this}

# 3. Test install as if you're a new user
./install.sh

# 4. Restore your data (database, configs)
./scripts/restore_claude_os.sh <timestamp>
./start.sh

Scenario 2: Test setup.sh from scratch

# 1. Backup everything
./scripts/backup_claude_os.sh

# 2. Full clean (simulate fresh machine)
./stop_all_services.sh
rm -rf venv venv_*
rm -rf node_modules
rm -rf data/claude-os.db
rm ~/.claude/commands/claude-os-*.md
rm ~/.claude/skills/{memory,initialize-project,remember-this}

# 3. Test full setup
./setup.sh
./start_all_services.sh

# 4. Restore your data
./scripts/restore_claude_os.sh <timestamp>
./start.sh

Scenario 3: Test project initialization

# 1. Backup current state
./scripts/backup_claude_os.sh

# 2. Create test project
cd ~/test-project
/claude-os-init  # In Claude Code

# 3. If something breaks, restore
cd ~/Projects/claude-os
./scripts/restore_claude_os.sh <timestamp>

---

Backup Best Practices

When to Backup

• Before testing installations - Always!
• Before major changes - Modifying core files
• Weekly - If actively developing
• Before upgrades - Git pull, dependency updates

Backup Management

# List all backups
ls -lh backups/

# Check backup size
du -sh backups/backup_*

# Remove old backups (keep last 5)
cd backups
ls -t | tail -n +6 | xargs rm -rf

# Archive old backups
tar -czf backups_archive_2025.tar.gz backups/

Multiple Backups

The backup script creates new backups each time - it never overwrites:

./scripts/backup_claude_os.sh  # Creates backup_20251101_135211
./scripts/backup_claude_os.sh  # Creates backup_20251101_140530
./scripts/backup_claude_os.sh  # Creates backup_20251101_141005

You can safely run it multiple times!

---

Troubleshooting

"Backup location not found"

# List available backups
ls -1 backups/ | grep backup_

# Use exact timestamp from list
./scripts/restore_claude_os.sh 20251101_135211

"Permission denied"

# Make scripts executable
chmod +x scripts/backup_claude_os.sh scripts/restore_claude_os.sh

"Database locked" during backup

# Stop services first
./stop_all_services.sh

# Then backup
./scripts/backup_claude_os.sh

Restore doesn't fix everything

The restore script restores data but not:

• Python packages (run pip install -r requirements.txt)
• Node modules (run cd frontend && npm install)
• Symlinks (run ./install.sh)
• Running services (run ./start.sh)

Full recovery process:

./scripts/restore_claude_os.sh <timestamp>
./install.sh  # Recreate symlinks
./start.sh    # Start services

---

File Locations Reference

Backed Up Locations

claude-os/
├── data/
│   ├── claude-os.db          ← BACKED UP (critical!)
│   └── uploads/              ← BACKED UP
├── .env                      ← BACKED UP (has secrets)
├── claude-os-config.json     ← BACKED UP
├── claude-os-state.json      ← BACKED UP
├── claude-os-triggers.json   ← BACKED UP
└── logs/                     ← BACKED UP (recent only)

~/.claude/
├── commands/claude-os-*.md   ← Symlink info recorded
└── skills/{memory,etc}       ← Symlink info recorded

Backup Storage Location

claude-os/
└── backups/
    ├── backup_20251101_135211/
    │   ├── claude-os.db
    │   ├── .env
    │   ├── claude-os-config.json
    │   ├── claude-os-state.json
    │   ├── claude-os-triggers.json
    │   ├── uploads/
    │   ├── logs/
    │   ├── symlink_info.txt
    │   └── MANIFEST.txt
    └── backup_20251101_140530/
        └── ...

---

Security Notes

.env File Contains Secrets

The .env file may contain:

• CLAUDE_OS_PASSWORD - Admin password
• CLAUDE_OS_SECRET_KEY - JWT secret
• API keys (if using OpenAI)

Backups are stored locally in backups/ directory.

⚠️ DO NOT:

• Commit backups to git (.gitignore already excludes them)
• Share backup directories
• Store backups in public locations

Recommended Backup Security

# Encrypt sensitive backups
tar -czf - backups/backup_20251101_135211 | \
  openssl enc -aes-256-cbc -pbkdf2 -out backup_encrypted.tar.gz.enc

# Decrypt when needed
openssl enc -aes-256-cbc -pbkdf2 -d -in backup_encrypted.tar.gz.enc | \
  tar -xzf -

---

Summary

You now have:

✅ backup_claude_os.sh - Backup all your data ✅ restore_claude_os.sh - Restore from backup ✅ Safe testing workflow ✅ Your first backup created!

Next steps:

1. Your backup is ready: backups/backup_20251101_135211/
2. You can safely test ./install.sh
3. If anything breaks: ./scripts/restore_claude_os.sh 20251101_135211
4. Test away with confidence! 🚀

---

Questions?

• Check backups/backup_*/MANIFEST.txt for backup contents
• Run ./scripts/restore_claude_os.sh with no arguments to list backups
• Backups are fast (30 seconds) - backup often!