claude-os/docs/guides/START_SCRIPTS_GUIDE.md

Start Scripts Guide

Claude OS has two different start scripts for different use cases:

---

1. ./start.sh - MCP Server Only

What it starts:

• ✅ MCP Server (port 8051)

What it does NOT start:

• ❌ Frontend Web UI
• ❌ Redis
• ❌ RQ Workers
• ❌ Ollama

Use when:

• You only need Claude Code integration
• You don't need the visual web interface
• You want minimal services running
• Quick start for development

Command:

./start.sh

Output:

✅ Claude OS MCP Server is running!

   📡 MCP Server: http://localhost:8051
      (For Claude Code integration - do NOT open in browser)

💡 Want the full experience?
To start ALL services: ./start_all_services.sh

What you can do:

• ✅ Use Claude Code with /claude-os-init
• ✅ Use Claude Code commands (/claude-os-search, etc.)
• ❌ Can't access web UI (no frontend running)
• ❌ No real-time learning (no workers running)

---

2. ./start_all_services.sh - Everything

What it starts:

• ✅ Ollama (port 11434) - Local AI models
• ✅ Redis (port 6379) - Cache & job queue
• ✅ RQ Workers - Background job processing
• ✅ MCP Server (port 8051) - API for Claude Code
• ✅ React Frontend (port 5173) - Web UI

Use when:

• You want the complete experience
• You need the web interface
• You want real-time learning features
• Production-like environment

Command:

./start_all_services.sh

Output:

==================================================
✅ All Services Started Successfully!
==================================================

📡 Service URLs:
   🎨 Frontend:    http://localhost:5173
   🔌 API Server:  http://localhost:8051
   📚 API Docs:    http://localhost:8051/docs

🔧 Ollama:
   Host:    http://localhost:11434
   Models:  llama3.1:latest, nomic-embed-text:latest

💾 Databases:
   SQLite:  data/claude-os.db
   Redis:   localhost:6379

🤖 Real-Time Learning System:
   RQ Workers: listening on 3 queues

What you can do:

• ✅ Use Claude Code integration
• ✅ Open web UI at http://localhost:5173
• ✅ Browse knowledge bases visually
• ✅ Upload documents via UI
• ✅ Real-time learning system active
• ✅ Full feature set

---

Quick Comparison

Feature	start.sh	start_all_services.sh
MCP Server	✅ Port 8051	✅ Port 8051
Web UI	❌	✅ Port 5173
Ollama	❌ (must start manually)	✅ Auto-started
Redis	❌	✅ Auto-started
RQ Workers	❌	✅ Background jobs
Real-time Learning	❌	✅ Active
Startup Time	~1 second	~30 seconds
Resource Usage	Minimal	Moderate

---

Which Should You Use?

Use ./start.sh if:

• Just testing Claude Code integration
• Don't need web interface
• Want faster startup
• Minimal resource usage
• Development/debugging

Use ./start_all_services.sh if:

• Want full functionality
• Need web interface
• Want to browse/manage KBs visually
• Production or demo environment
• Want real-time learning features

---

Common Mistakes

❌ Mistake 1: Opening MCP server in browser

Problem:

./start.sh
# Then opening http://localhost:8051 in browser
# → "Method Not Allowed" error

Why: MCP server (port 8051) is for Claude Code API calls, not browsers

Solution:

• Don't open 8051 in browser
• Use ./start_all_services.sh and open http://localhost:5173 instead

❌ Mistake 2: Expecting Web UI with start.sh

Problem:

./start.sh
# Then trying to access http://localhost:5173
# → Connection refused

Why: start.sh doesn't start the frontend

Solution:

• Use ./start_all_services.sh instead

❌ Mistake 3: Wrong port numbers

Problem: Confusing which service runs on which port

Remember:

• Port 8051: MCP Server (for Claude Code) - Don't open in browser!
• Port 5173: Web UI (for humans) - Open this in browser!

---

Stopping Services

Stop MCP Server Only (start.sh)

Option 1: Press Ctrl+C in the terminal

Option 2: Kill by PID

# PID shown when you start it
kill <PID>

Stop All Services (start_all_services.sh)

Use the stop script:

./stop_all_services.sh

This will stop:

• MCP Server
• Frontend
• RQ Workers
• Redis (optional)
• Ollama (optional)

---

Restarting Services

Restart MCP Only

# Stop (Ctrl+C or kill PID)
./start.sh

Restart Everything

./restart_services.sh

Or manually:

./stop_all_services.sh
./start_all_services.sh

---

Logs

MCP Server Logs

If started with start.sh:

• Output shows in terminal

If started with start_all_services.sh:

tail -f logs/mcp_server.log

Frontend Logs

tail -f logs/frontend.log

RQ Workers Logs

tail -f logs/rq_workers.log

All Logs

tail -f logs/*.log

---

Installation Recommendation

After running ./install.sh, the README says:

1️⃣  Start Claude OS:
    ./start.sh

But for the full experience, you should use:

1️⃣  Start Claude OS (all services):
    ./start_all_services.sh

Then you can:

• Use Claude Code at port 8051
• Open web UI at http://localhost:5173
• Have full functionality

---

Summary

Remember:

• ./start.sh = MCP server only (minimal, fast)
• ./start_all_services.sh = Everything (full features)

For most users:

./start_all_services.sh  # ← Recommended!

Then access:

• Web UI: http://localhost:5173 ✅ Open in browser
• MCP Server: http://localhost:8051 ❌ Don't open in browser (for Claude Code only)

Problem solved! 🎉