claudetools/NEW_MACHINE_SETUP.md

New Machine Setup - Complete ClaudeTools Clone (Cross-Platform)

This guide will help you set up a complete, identical ClaudeTools environment on a new machine (Windows or Mac).

Platform-Specific Notes:

• Windows commands shown as: Windows> command
• Mac/Linux commands shown as: Mac> command
• When only one command shown, it works on both platforms

---

Prerequisites

Required Software (All Platforms):

• Git (for cloning repository)
• Python 3.9+ (for ClaudeTools API)
• Node.js/npm (for MCP servers)
• Claude Code CLI installed
• SSH client (built-in on Mac/Linux, use Git Bash or OpenSSH on Windows)

Installation:

# Mac (using Homebrew)
Mac> brew install git python node

# Windows (using winget or Chocolatey)
Windows> winget install Git.Git Python.Python.3.11 OpenJS.NodeJS
# OR
Windows> choco install git python nodejs

---

Step 1: Clone Repository from Gitea

Choose Your Project Location:

# Windows
Windows> cd D:\
Windows> git clone ssh://azcomputerguru@172.16.3.20:2222/azcomputerguru/claudetools.git ClaudeTools
Windows> cd ClaudeTools

# Mac
Mac> cd ~/Projects  # or wherever you want it
Mac> git clone ssh://azcomputerguru@172.16.3.20:2222/azcomputerguru/claudetools.git ClaudeTools
Mac> cd ClaudeTools

Note: You'll need SSH access to the Gitea server (172.16.3.20:2222)

For This Guide:

• Windows path: D:\ClaudeTools
• Mac path: ~/Projects/ClaudeTools (adjust as needed)

---

Step 2: Set Up Python Virtual Environment

# Create virtual environment (both platforms)
python -m venv api/venv

# Activate virtual environment
Windows> api\venv\Scripts\activate
Mac> source api/venv/bin/activate

# Install Python dependencies (both platforms, once activated)
pip install -r requirements.txt

# Install development dependencies (if needed)
pip install -r requirements-dev.txt

Verify Activation:

# You should see (venv) in your prompt
# Check Python location:
Windows> where python
Mac> which python
# Should show path inside api/venv/

---

Step 3: Configure Environment Variables

Copy Environment Template:

Windows> copy .env.example .env
Mac> cp .env.example .env

Edit .env:

Windows> notepad .env
Mac> nano .env  # or vim .env, or use VS Code: code .env

Required Variables in .env:

# Database Configuration
DATABASE_URL=mysql+pymysql://claudetools:CT_e8fcd5a3952030a79ed6debae6c954ed@172.16.3.30:3306/claudetools?charset=utf8mb4

# JWT Configuration
JWT_SECRET_KEY=your-jwt-secret-key-here
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

# Encryption Configuration
ENCRYPTION_KEY=your-fernet-encryption-key-here

# API Configuration
API_HOST=0.0.0.0
API_PORT=8000

Get actual values from credentials.md in the repository!

---

Step 4: Set Up MCP Servers

The .mcp.json file needs platform-specific paths.

Windows - Edit .mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      }
    },
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "D:\\ClaudeTools"]
    },
    "sequential-thinking": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Mac - Edit .mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourusername/Projects/ClaudeTools"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Important for Mac: Update the filesystem path to match your actual ClaudeTools location!

Verify npm is installed:

npm --version
# Should show version number (18.0.0 or higher)

MCP servers will auto-install on first use via npx

---

Step 5: Test Database Connection

# Activate venv if not already active
Windows> api\venv\Scripts\activate
Mac> source api/venv/bin/activate

# Test database connection (both platforms)
python test_db_connection.py

Expected output: Connection successful to 172.16.3.30:3306/claudetools

Note: Ensure you have network access to 172.16.3.30:3306 (MariaDB server)

---

Step 6: Run Database Migrations (if needed)

# Check current migration status (both platforms)
alembic current

# Upgrade to latest (if needed)
alembic upgrade head

---

Step 7: Test API Server

# Activate venv first
Windows> api\venv\Scripts\activate
Mac> source api/venv/bin/activate

# Start the API server (both platforms)
python -m api.main

# Or use uvicorn directly
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

Test endpoints:

• Local: http://localhost:8000/api/docs
• Network: http://172.16.3.30:8001/api/docs (if running on RMM server)

Stop Server: Press Ctrl+C

---

Step 8: Configure SSH Keys for Infrastructure

Generate SSH Key (if you don't have one):

# Both platforms
ssh-keygen -t ed25519 -C "your_email@example.com"
# Press Enter to accept default location
# Enter passphrase (optional but recommended)

For AD2 (Windows Server):

• Host: 192.168.0.6
• User: INTRANET\sysadmin
• Password: See credentials.md
• Note: Password authentication (SSH keys not typically used with Windows domain accounts)

For D2TESTNAS (Linux NAS):

# Copy your SSH key to the NAS
ssh-copy-id root@192.168.0.9

# Test connection (both platforms)
ssh root@192.168.0.9 "ls /data/test/COMMON/ProdSW/"

For Gitea Server:

# Test Gitea SSH access (both platforms)
ssh -p 2222 azcomputerguru@172.16.3.20

# Should show Gitea greeting, then disconnect

Mac-Specific SSH Notes:

• Keys stored in: ~/.ssh/
• Config file: ~/.ssh/config
• Permissions must be correct: chmod 600 ~/.ssh/id_ed25519

Windows-Specific SSH Notes:

• Keys stored in: C:\Users\YourName\.ssh\
• Use Git Bash or PowerShell for SSH commands
• OpenSSH should be installed (Windows 10+)

---

Step 9: Update File Paths in Context Recovery Prompt

The context recovery prompt has Windows paths. Update them for your platform:

For Mac, change:

• D:\ClaudeTools → /Users/yourusername/Projects/ClaudeTools
• Or use relative paths (just PROJECT_ORGANIZATION.md instead of full path)

Context Recovery Prompt (Platform-Agnostic Version):

See CONTEXT_RECOVERY_PROMPT.md in the repository. When pasting to Claude Code, use paths appropriate for your platform:

Working directory: D:\ClaudeTools          (Windows)
Working directory: ~/Projects/ClaudeTools   (Mac)

---

Step 10: Restore Full Context in Claude Code

Open Claude Code in your ClaudeTools directory:

Windows> cd D:\ClaudeTools
Mac> cd ~/Projects/ClaudeTools

Then paste the context recovery prompt from CONTEXT_RECOVERY_PROMPT.md

The prompt will tell Claude to read all necessary files and restore full context including:

• Project states (DOS, API, clients)
• Credentials and infrastructure access
• Organization system
• MCP servers, commands, and skills

---

Step 11: Verify Everything Works

Test Checklist:

• Python venv activates
• Database connection successful (172.16.3.30:3306)
• API server starts and responds (http://localhost:8000/api/docs)
• SSH to D2TESTNAS works (ssh root@192.168.0.9)
• SSH to Gitea works (ssh -p 2222 azcomputerguru@172.16.3.20)
• Claude Code loads in ClaudeTools directory
• MCP servers load (check Claude Code startup messages)
• Context recovery prompt works
• Available commands show: /save, /context, /checkpoint, etc.
• Git push to Gitea works

---

Platform-Specific Quick Reference

Windows

Start API:

cd D:\ClaudeTools
api\venv\Scripts\activate
python -m api.main

File Paths:

• Project root: D:\ClaudeTools
• Venv: D:\ClaudeTools\api\venv
• Credentials: D:\ClaudeTools\credentials.md

Deploy to DOS:

scp file.BAT root@192.168.0.9:/data/test/COMMON/ProdSW/

Mac

Start API:

cd ~/Projects/ClaudeTools
source api/venv/bin/activate
python -m api.main

File Paths:

• Project root: ~/Projects/ClaudeTools
• Venv: ~/Projects/ClaudeTools/api/venv
• Credentials: ~/Projects/ClaudeTools/credentials.md

Deploy to DOS:

scp file.BAT root@192.168.0.9:/data/test/COMMON/ProdSW/

---

Cross-Platform Notes

What's the Same:

• Git commands (clone, commit, push, pull)
• Python/pip commands (once venv activated)
• SSH commands (ssh, scp)
• Database access (same connection string)
• API endpoints (same URLs)
• File organization structure

What's Different:

• Path separators: \ (Windows) vs / (Mac/Linux)
• Venv activation: Scripts\activate vs bin/activate
• File copy: copy vs cp
• Text editors: notepad vs nano/vim
• MCP .mcp.json: cmd /c npx vs just npx
• Absolute paths: D:\ vs /Users/ or ~

---

Troubleshooting

MCP servers not loading:

• Restart Claude Code completely
• Check npm is installed: npm --version
• Check .mcp.json is valid JSON
• Mac: Verify paths use forward slashes: /Users/...
• Windows: Verify paths use double backslashes: D:\\...

Database connection fails:

• Verify network access to 172.16.3.30:3306
• Mac: Check firewall settings (System Preferences → Security)
• Windows: Check Windows Firewall
• Test with: python test_db_connection.py

SSH keys not working:

# Mac: Fix permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

# Windows: Use Git Bash for SSH operations
# Or ensure OpenSSH is installed and running

API won't start:

# Check port 8000 not in use
Windows> netstat -ano | findstr :8000
Mac> lsof -i :8000

# Verify venv is activated (should see (venv) in prompt)
# Check all dependencies: pip list

Git push fails:

# Ensure SSH key is added to Gitea
# Test connection:
ssh -p 2222 azcomputerguru@172.16.3.20

# Check remote URL:
git remote -v

---

What You Now Have (All Platforms)

Complete Environment:

• ✅ All project files organized by project/client
• ✅ Full git history from Gitea
• ✅ Python API environment configured
• ✅ MCP servers ready to use
• ✅ SSH access to infrastructure (D2TESTNAS, Gitea)
• ✅ Database connection to MariaDB (172.16.3.30)
• ✅ All credentials and context
• ✅ All commands and skills available

Full Context:

• ✅ Dataforth DOS project status and history
• ✅ ClaudeTools API development history
• ✅ Client history (Horseshoe Management)
• ✅ Infrastructure access details
• ✅ Recent work and decisions

Works On:

• ✅ Windows 10/11
• ✅ macOS (Intel and Apple Silicon)
• ✅ Linux (Ubuntu, Debian, etc.)

---

Next Steps After Setup

1. Test DOS deployment on TS-4R (pending from last session)
2. Continue API development (Phase 5 complete, optional Phase 7 available)
3. Handle client support requests (Horseshoe Management, etc.)

All work will automatically be organized into correct project/client folders and synced back to Gitea.

---

Setup Complete! You now have an identical ClaudeTools environment on your new machine, whether it's Windows, Mac, or Linux.

---

Last Updated: 2026-01-20 File Location: NEW_MACHINE_SETUP.md (in Gitea repository) Platforms: Windows, macOS, Linux