marclar/mac-studio-to-nuc-migration-plan.md

OpenClaw Migration Plan: Mac Studio → NUC

Migration Date: TBD (Mac Studio return planned)
Current Setup: Mac Studio (M2 Ultra, macOS 15.2, ARM64)
Target Setup: Intel NUC (Linux-based, likely Ubuntu/Debian, x86_64)

⚠️ Updated Requirements:

No local models (NUC not powerful enough)
Default model: Claude Sonnet (anthropic/claude-sonnet-4-20250514)
Must install Claude Code CLI
Discard workspace repos (will re-clone fresh)
Discard session history (fresh start)
Re-establish Slack/Signal connections

📋 Pre-Migration Checklist

Current State Assessment

OpenClaw Gateway: Running as LaunchAgent (PID 67650)
Active Sessions: 1712 sessions, main agent active
Models: Default qwen3-coder-next:latest (local) → WILL CHANGE TO: Claude Sonnet (cloud-only)
Channels: Slack + Signal configured and operational → WILL NEED: Re-establishment on NUC
Security: 3 critical + 3 warn + 1 info (mainly Slack groupPolicy="open")
Storage: 11GB used of 926GB available (~720GB free)
Workspace: /Users/cb/.openclaw/workspace (~2.2GB with cerebruh.is repo)

Critical Data Inventory

OpenClaw Configuration
- ~/.openclaw/openclaw.json (6.8KB, modified Mar 8)
- Agent configurations in ~/.openclaw/agents/
- Session history in ~/.openclaw/agents/main/sessions/
Credentials & Secrets
- BWS access token and profile config
- GitHub SSH key: ~/.openclaw/workspace/.ssh/github_marclar
- All API keys stored in Bitwarden Secrets (remote, safe)
- Slack/Signal: Connection tokens (will need re-auth on NUC)
Workspace Data ✂️ SIMPLIFIED
- Documentation: AGENTS.md, SOUL.md, USER.md, etc.
- Memory files: MEMORY.md + memory/*.md
- ~~Repository clones~~ (will re-clone fresh)
- ~~Session history~~ (fresh start on NUC)
Platform-Specific Dependencies
- Node.js + OpenClaw
- Claude Code CLI (required for GitHub automation)
- BWS CLI from Bitwarden
- Git, curl, basic CLI tools

🚀 Migration Strategy

Phase 1: Environment Setup (NUC Preparation)

Install Base OS (Ubuntu LTS or Debian Stable)
Install Node.js (v25.7.0+ to match current)

Install OpenClaw

npm install -g openclaw
# or curl install script

Install Required Tools
- git, curl, wget
- Claude Code CLI (critical for GitHub automation)
- BWS CLI from Bitwarden
- Basic development tools

Phase 2: Data Migration

Export OpenClaw Configuration ✂️ SELECTIVE

# On Mac Studio - only config + memory, skip sessions
mkdir migration-data
cp ~/.openclaw/openclaw.json migration-data/
cp -r ~/.openclaw/workspace/memory migration-data/
cp ~/.openclaw/workspace/{AGENTS,SOUL,USER,TOOLS,MEMORY,IDENTITY,HEARTBEAT}.md migration-data/
cp ~/.openclaw/workspace/.ssh migration-data/ -r
tar -czf migration-essentials.tar.gz migration-data/

Skip Large Data 🚫
- ~~Session history~~ (fresh start)
- ~~Repository clones~~ (will re-clone)
- ~~Local models~~ (cloud-only on NUC)
Secure Transfer
- Transfer only migration-essentials.tar.gz (~few MB vs GB)
- Verify checksums after transfer

Import on NUC

# On NUC
tar -xzf migration-essentials.tar.gz
cp migration-data/openclaw.json ~/.openclaw/
mkdir -p ~/.openclaw/workspace
cp migration-data/*.md ~/.openclaw/workspace/
cp -r migration-data/memory ~/.openclaw/workspace/
cp -r migration-data/.ssh ~/.openclaw/workspace/

Phase 3: Service Configuration

Initialize OpenClaw Gateway

openclaw gateway start
openclaw status  # verify

Configure BWS Authentication

bws config  # re-auth if needed
# Test access to key credentials

Verify Channel Connectivity
- Test Slack bot connection
- Test Signal integration
- Verify GitHub API access
Model Configuration 🌐 CLOUD-ONLY
- Set default model to anthropic/claude-sonnet-4-20250514
- Verify Anthropic API access
- Test Claude Code CLI functionality
- Remove any local model references from config

Phase 4: Service Migration

Update External Service Endpoints
- Hetzner VMs: Update any hardcoded Mac Studio IPs
- Webhooks: Redirect to NUC endpoints if applicable
- DNS/networking: Ensure NUC is reachable
Cron Jobs & Automation
- Migrate any scheduled tasks
- Verify GitHub agent automation works
- Test heartbeat functionality
Security Hardening
- Address security audit findings
- Configure firewall rules
- Set up proper systemd services (vs macOS LaunchAgents)

⚠️ Migration Risks & Mitigation

Architecture Differences (ARM64 → x86_64)

Risk: Binary incompatibility, especially local models
Mitigation: Download x86_64 versions of all binaries
Specific Concern: Local qwen3-coder model may need re-download

Claude Code CLI Requirement ⚠️ CRITICAL

Risk: Claude Code CLI availability/installation on Linux x86_64
Mitigation:
- Test installation during Phase 1 (required before proceeding)
- GitHub automation depends on this - no fallback to local models
- If unavailable: Must revise GitHub agent workflow to use sessions_spawn + API

Channel Re-establishment

Risk: Slack/Signal connections lost, need fresh setup
Mitigation:
- Slack: Re-authenticate bot tokens, verify workspace permissions
- Signal: May need device re-registration (QR code process)
- Document new connection process for future reference

Platform-Specific Features

Risk: macOS-specific integrations may break
Mitigation:
- Audit current skills for macOS dependencies
- Replace with Linux equivalents where possible
- Document any lost functionality

Service Interruption

Risk: Downtime during migration
Mitigation:
- Perform migration during low-activity period
- Keep Mac Studio running until NUC is fully verified
- Gradual cutover with rollback plan

🔍 Testing & Validation Plan

Core Functionality Tests

OpenClaw Gateway
- Dashboard accessible
- WebSocket connections stable
- Agent spawning works
Channel Integration
- Slack bot responds to mentions
- Signal messages route correctly
- Message delivery and reactions work
GitHub Automation
- GitHub agent can scan issues
- Claude Code integration functional
- PR creation and merging works
- CI gate scripts execute
Model Access 🌐 CLOUD-ONLY
- ~~Local models~~ (not using on NUC)
- Anthropic API calls succeed
- Claude Code CLI responds correctly
- Token usage tracking accurate
- Default model set to Claude Sonnet
Workspace Operations
- File read/write operations
- Git operations (clone, push, pull)
- BWS credential access
- Memory search functionality

📅 Rollback Plan

If migration fails or issues arise:

Keep Mac Studio Available
- Don't wipe until NUC is 100% validated
- Maintain parallel operation initially

Quick Revert Procedure

# On Mac Studio
openclaw gateway start  # if stopped
# Update any external service endpoints back

Data Sync Back
- If work happened on NUC, sync changes back to Mac Studio
- Ensure no data loss during transition

🎯 Post-Migration Optimization

Performance Tuning

Monitor CPU/memory usage vs Mac Studio baseline
Adjust concurrent agent limits if needed
~~Local model optimization~~ (cloud-only setup)
Monitor Anthropic API rate limits and costs

Security Review

Complete security audit on new platform
Implement systemd service isolation
Configure proper user permissions
Set up fail2ban or similar protection

Monitoring Setup

Set up health check automation
Configure log rotation
Implement backup schedules for critical data

📝 Migration Log Template

## Migration Execution Log

### Pre-Migration (Date: _______)
- [ ] Mac Studio data backed up
- [ ] NUC environment ready
- [ ] All stakeholders notified

### Migration Day (Date: _______)
- [ ] Data transferred successfully
- [ ] OpenClaw started on NUC
- [ ] Basic functionality verified
- [ ] Channels responding
- [ ] GitHub integration tested

### Post-Migration (Date: _______)
- [ ] 24-hour stability confirmed  
- [ ] Performance benchmarked
- [ ] All automation verified
- [ ] Mac Studio safely decommissioned

Estimated Migration Time: 3-4 hours ⏰ SIMPLIFIED
Recommended Migration Window: Weekend or low-activity period
Success Criteria:

OpenClaw gateway running on NUC
Claude Code CLI functional
Slack/Signal channels re-connected
GitHub automation working
Essential files preserved (configs, memory, docs)

What We're NOT Preserving:

Session history (fresh start)
Repository clones (re-clone as needed)
Local models (cloud-only on NUC)