Installation

Full installation reference for CrewHub. If you just want to get up and running quickly, see Quick Start.

System Requirements

Component	Minimum	Recommended
OS	macOS 12, Ubuntu 20.04, Windows 10	macOS 14+, Ubuntu 22.04+
Python	3.11	3.12
Node.js	18 LTS	20 LTS
RAM	2 GB	4 GB+
Disk	500 MB	1 GB+

Clone the Repository

git clone https://github.com/EKINSOL-DEV/crewhub.git
cd crewhub

Setup Options

Option A — Script (Recommended)

The setup script handles everything: Python venv creation, pip install, npm install, and config generation.

# Mac / Linux
./scripts/setup.sh

# Windows
.\scripts\setup.ps1

Option B — Make

make setup

Option C — Manual

# Backend
cd backend
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Frontend
cd ../frontend
npm install

Environment Variables

CrewHub reads from .env files in both backend/ and frontend/. The setup script creates defaults automatically.

Backend (backend/.env)

Variable	Default	Description
PORT	8090	Backend API port
HOST	0.0.0.0	Bind address
DB_PATH	~/.crewhub/crewhub.db	SQLite database location
CLAUDE_PROJECTS_DIR	Auto-detected	Path to ~/.claude/projects/

Frontend (frontend/.env)

Variable	Default	Description
VITE_API_BASE	http://localhost:8090	Backend API URL

Starting CrewHub

# Script
./scripts/start.sh

# Make
make dev

# Manual (two terminals)
# Terminal 1 — backend
cd backend && source venv/bin/activate && uvicorn app.main:app --host 0.0.0.0 --port 8090 --reload

# Terminal 2 — frontend
cd frontend && npm run dev

Verify It's Running

# Health check
curl http://localhost:8090/health
# → {"status":"ok","version":"0.19.5"}

Open http://localhost:5181 in your browser.

Troubleshooting

Port already in use

# Find what's using port 8090
lsof -i :8090

# Use a different port
PORT=8091 ./scripts/start.sh

Python version mismatch

python3 --version   # Must be 3.11+
# On some systems use: python3.11 or python3.12

Node modules missing

cd frontend && npm install