claude-os/docs/README_NATIVE_SETUP.md

Native Claude OS Setup (No Docker)

This guide covers running Claude OS natively on your M4 Pro Mac with Metal GPU acceleration.

Prerequisites

1. PostgreSQL (Required for MCP Server)

If you don't have PostgreSQL installed, install it:

# Option A: Via Homebrew (recommended)
brew install postgresql@16
brew services start postgresql@16

# Option B: Download from https://www.postgresql.org/download/macosx/

# Verify it's running
psql --version
psql -h localhost -U $USER -d postgres -c "SELECT 1"

Once PostgreSQL is running, create the database:

createdb codeforge

2. Ollama (For LLM)

Already installed via Homebrew in the previous steps. It should be running with:

brew services start ollama

3. Node.js (For React Frontend)

# Check if installed
node --version

# If not installed
brew install node

4. Python 3.11+ (For MCP Server)

python3 --version

Quick Start

Once all prerequisites are installed and running:

# From the project directory
cd ~/Projects/claude-os

# Start all services
./start_all_services.sh

This will:

1. ✅ Check PostgreSQL is running
2. ✅ Check/Start Ollama
3. ✅ Setup Python virtual environment
4. ✅ Start MCP Server (port 8051)
5. ✅ Start React Frontend (port 5173)

Service URLs

Once everything is running:

• Frontend UI: http://localhost:5173
• MCP Server: http://localhost:8051
• API Endpoint: http://localhost:8051/api
• MCP Endpoint: http://localhost:8051/mcp/kb/pistn

Stopping Services

./stop_all_services.sh

Logs

Service logs are stored in the logs/ directory:

# Watch MCP server logs
tail -f logs/mcp_server.log

# Watch frontend logs
tail -f logs/frontend.log

Environment Variables

The system uses environment variables from:

# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=codeforge
POSTGRES_USER=$USER
POSTGRES_PASSWORD=

# Ollama
OLLAMA_HOST=http://localhost:11434

# MCP Server
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8051

Performance

With native setup on M4 Pro:

• Query Response Time: 2-5 seconds (vs 30-45s with Docker)
• GPU Acceleration: Full Metal GPU support
• RAM Usage: ~8-10GB for models + app
• CPU Utilization: 12 cores (leave 2 for system)

Troubleshooting

"PostgreSQL not running"

brew services start postgresql@16
# or find your postgresql version
brew services list

"Ollama models not found"

ollama pull llama3.1:latest
ollama pull nomic-embed-text:latest

"Port already in use"

# Port 8051 (MCP Server)
lsof -i :8051 | grep -v COMMAND | awk '{print $2}' | xargs kill -9

# Port 5173 (Frontend)
lsof -i :5173 | grep -v COMMAND | awk '{print $2}' | xargs kill -9

"npm packages not installed"

cd frontend
npm install
npm run dev -- --host 0.0.0.0

Architecture

localhost:5173 (React Frontend)
    ↓
localhost:8051 (FastAPI MCP Server)
    ↓
localhost:11434 (Ollama with Metal GPU)
    ↓
localhost:5432 (PostgreSQL)

For Claude (Me)

The MCP server is configured to expose:

• Global endpoint: /mcp - All knowledge bases and tools
• KB-specific endpoint: /mcp/kb/pistn - Pistn KB only

Query examples:

curl -X POST http://localhost:8051/mcp/kb/pistn \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {
        "query": "appointment settings"
      }
    },
    "id": 1
  }'

System Requirements

• CPU: M4 Pro or similar Apple Silicon (14+ cores)
• RAM: 48GB (or 32GB minimum)
• Storage: ~10GB for models + application
• macOS: 12.0+

Enjoy your high-performance local MCP server! 🚀