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. Ollama (For LLM)

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

brew services start ollama

2. Node.js (For React Frontend)

# Check if installed
node --version

# If not installed
brew install node

3. 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/Start Ollama
2. ✅ Setup Python virtual environment
3. ✅ Initialize SQLite database
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:

# SQLite Database
SQLITE_DB_PATH=data/claude-os.db

# 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

"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)
    ↓
data/claude-os.db (SQLite + sqlite-vec)

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! 🚀