mindX.sh Quick Reference Guide

🚀 Quick Start

Basic Deployment

# Make executable
chmod +x mindX.sh

Deploy and start services
./mindX.sh --run /opt/mindx

Development Setup

# Quick dev setup with debug logging
./mindX.sh --log-level DEBUG --run ~/mindx-dev

Interactive setup with API keys
./mindX.sh --interactive --run ~/mindx-dev

Production Deployment

# Production with custom config
./mindX.sh --config-file prod-config.json \
           --dotenv-file prod.env \
           --log-level WARNING \
           /opt/mindx-production

📋 Command Line Options

OptionDescriptionExample --runStart services after setup./mindX.sh --run /opt/mindx --config-fileUse existing config--config-file /path/config.json --dotenv-fileUse existing .env--dotenv-file /path/.env --interactivePrompt for API keys--interactive --venv-nameCustom venv name--venv-name myenv --frontend-portFrontend port--frontend-port 3000 --backend-portBackend port--backend-port 8000 --log-levelLog level--log-level DEBUG -h, --helpShow help./mindX.sh --help

🔧 Service Management

Check Status

# Check if running
ps aux | grep -E "(uvicorn|node server.js)"

Check PIDs
cat /opt/mindx/data/pids/mindx_backend.pid
cat /opt/mindx/data/pids/mindx_frontend.pid

View Logs

# Backend logs
tail -f /opt/mindx/data/logs/mindx_coordinator_service.log

Frontend logs
tail -f /opt/mindx/data/logs/mindx_frontend_service.log

Deployment logs
tail -f /opt/mindx/data/logs/mindx_deployment_setup.log

Stop Services

# Graceful stop (Ctrl+C)
Or manual stop:
kill $(cat /opt/mindx/data/pids/mindx_backend.pid)
kill $(cat /opt/mindx/data/pids/mindx_frontend.pid)

🌐 Access Points

Services

Backend API: http://localhost:8000

Frontend UI: http://localhost:3000

API Docs (Swagger UI): http://localhost:8000/docs — interactive API reference; use it to browse endpoints, try requests, and inspect request/response schemas. Best way to explore API interactions.

Key Endpoints

GET / - Root endpoint

POST /commands/evolve - Evolve codebase

POST /coordinator/query - Query coordinator

GET /status/mastermind - System status

GET /identities - List identities

⚙️ Configuration Files

Environment (.env)

# Key settings
MINDX_LOG_LEVEL="INFO"
MINDX_LLM__DEFAULT_PROVIDER="ollama"
GEMINI_API_KEY="your-key-here"
MISTRAL_API_KEY="your-mistral-key-here"

Interactive Setup

# Prompt for API keys during setup
./mindX.sh --interactive /opt/mindx

Will ask for:
- Gemini API Key (https://aistudio.google.com/app/apikey)
- Mistral AI API Key (https://console.mistral.ai/)

JSON Config (mindx_config.json)

{
  "system": {"version": "0.4.0"},
  "llm": {"providers": {"ollama": {"enabled": true}}},
  "tools": {"note_taking": {"enabled": true}}
}

🚨 Troubleshooting

Common Issues

Permission Denied

chmod +x mindX.sh
chmod 600 /opt/mindx/.env

Port Already in Use

# Check ports
netstat -tlnp | grep :8000
netstat -tlnp | grep :3000

Use different ports
./mindX.sh --backend-port 9000 --frontend-port 4000 /opt/mindx

Python/Node Not Found

# Install Python 3
sudo apt install python3 python3-venv

Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs

Service Won't Start

# Check logs
tail -f /opt/mindx/data/logs/mindx_deployment_setup.log

Check Python environment
/opt/mindx/.mindx_env/bin/python --version

Check dependencies
/opt/mindx/.mindx_env/bin/pip list

Debug Mode

# Enable debug logging
./mindX.sh --log-level DEBUG --run /opt/mindx

Check all logs
tail -f /opt/mindx/data/logs/*.log

📁 Directory Structure

/opt/mindx/
├── .mindx_env/                    # Python virtual environment
├── data/
│   ├── logs/                      # All log files
│   ├── pids/                      # Process ID files
│   └── config/                    # Configuration files
├── mindx_backend_service/         # Backend API
│   └── main_service.py
├── mindx_frontend_ui/             # Frontend UI
│   ├── index.html
│   ├── server.js
│   └── package.json
├── .env                          # Environment config
└── [mindx source code]           # Core modules

🔄 Maintenance

Update Dependencies

cd /opt/mindx
source .mindx_env/bin/activate
pip install --upgrade -r requirements.txt

Restart Services

# Stop services
pkill -f "uvicorn\|node server.js"

Start services
./mindX.sh --run /opt/mindx

Backup Configuration

# Backup config
tar -czf mindx-config-backup.tar.gz /opt/mindx/.env /opt/mindx/data/config/

🎯 Use Cases

Hackathon

# Quick setup
./mindX.sh --run ~/hackathon-mindx
Access: http://localhost:3000

Development

# Dev with debug
./mindX.sh --log-level DEBUG --run ~/mindx-dev
Edit code in ~/mindx-dev/

Production

# Production setup
./mindX.sh --config-file prod-config.json \
           --dotenv-file prod.env \
           --log-level WARNING \
           /opt/mindx

📞 Support

Logs Location

Deployment: /opt/mindx/data/logs/mindx_deployment_setup.log

Backend: /opt/mindx/data/logs/mindx_coordinator_service.log

Frontend: /opt/mindx/data/logs/mindx_frontend_service.log

Configuration Files

Environment: /opt/mindx/.env

JSON Config: /opt/mindx/data/config/mindx_config.json

Process Management

Backend PID: /opt/mindx/data/pids/mindx_backend.pid

Frontend PID: /opt/mindx/data/pids/mindx_frontend.pid

---