A lightweight, high-performance Linux VPS management panel with a pluggable architecture. Add new features just by dropping a module folder—no core code modifications needed!

• Start here first: AGENT_START_HERE.md
• Backend logic map: backend/ARCHITECTURE_AI.md
• Frontend logic map: frontend/ARCHITECTURE_AI.md

Pluggable Architecture: Automatically detect and register new features (Backend APIs + Frontend UI) just by adding a folder into a specific directory.

/copanel
├── backend/
│   ├── main.py                      # FastAPI entry point
│   ├── core/
│   │   ├── __init__.py
│   │   ├── loader.py               # Dynamic module loader
│   │   └── security.py             # JWT & auth utilities
│   ├── modules/                     # 🔌 PLUGIN FOLDER
│   │   ├── system_monitor/         # Reference module 1
│   │   │   ├── __init__.py
│   │   │   ├── router.py           # Must export 'router'
│   │   │   └── logic.py
│   │   └── file_manager/           # Reference module 2 (create your own!)
│   └── requirements.txt
│
├── frontend/
│   ├── src/
│   │   ├── core/
│   │   │   ├── registry.ts         # Dynamic module registry
│   │   │   ├── Layout.tsx          # Main layout with sidebar
│   │   │   └── routes.tsx          # Dynamic routing
│   │   ├── modules/                # 🔌 UI PLUGIN FOLDER
│   │   │   ├── system_monitor/
│   │   │   │   ├── index.tsx
│   │   │   │   └── config.ts
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── package.json
│   ├── vite.config.ts
│   └── tailwind.config.js
│
├── scripts/
│   └── install.sh                  # One-click installation
│
├── config/
│   └── nginx.conf                  # Nginx template
│
└── README.md

• Linux (Ubuntu 20.04+, CentOS 8+, Debian 11+)
• Root or sudo access
• Python 3.10+
• Node.js 18+

curl -sSL https://raw.githubusercontent.com/phuspeed/CoPanel/main/scripts/install.sh | sudo bash

The installer will:

• ✅ Install system dependencies
• ✅ Create Python virtual environment
• ✅ Install backend & frontend dependencies
• ✅ Build frontend assets
• ✅ Configure Nginx reverse proxy (port 8686)
• ✅ Set up Systemd service
• ✅ Start all services

• Web UI: http://localhost:8686
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

1. Create folder: backend/modules/{your_module}/
2. Create router.py and export a FastAPI router:

from fastapi import APIRouter

router = APIRouter()

@router.get("/info")
async def get_info():
    return {"message": "Your module works!"}

3. Create __init__.py (empty is fine)
4. Restart service: systemctl restart copanel

The module loads automatically at /api/{your_module}!

1. Create folder: frontend/src/modules/{your_module}/
2. Create config.ts:

import YourComponent from './index';

export default {
  name: 'Your Module',
  icon: 'Grid',  // Lucide icon name
  path: '/your-module',
  component: YourComponent,
  description: 'Your module description',
};

3. Create index.tsx with your React component
4. Rebuild: npm run build (in frontend folder)

The module appears automatically in the sidebar!

The included System Monitor module demonstrates the pluggable architecture:

• GET /api/system_monitor/stats - All system stats
• GET /api/system_monitor/cpu - CPU metrics
• GET /api/system_monitor/memory - Memory metrics
• GET /api/system_monitor/disk - Disk metrics
• GET /api/system_monitor/network - Network stats

• Real-time CPU/Memory charts (Recharts)
• Disk usage visualization
• System information display
• Auto-updating every 3 seconds

• ✅ No shell=True in subprocess calls (prevents injection)
• ✅ Input sanitization on all user inputs
• ✅ JWT token-based authentication
• ✅ HTTPS ready (use with your certificate)
• ✅ CORS configured for development
• ✅ Systemd service runs as unprivileged user

# Start
systemctl start copanel

# Stop
systemctl stop copanel

# Restart
systemctl restart copanel

# View logs
journalctl -u copanel -f

# Check status
systemctl status copanel

cd backend
source venv/bin/activate
pip install -r requirements.txt
python -m uvicorn main:app --reload

API will be available at http://localhost:8000 Interactive docs at http://localhost:8000/docs

cd frontend
npm install
npm run dev

Frontend dev server at http://localhost:5173 (Auto-proxies API calls to http://localhost:8000)

• Scans backend/modules/ directory
• Looks for router.py in each module folder
• Dynamically imports and registers routers
• Assigns URL prefix /api/{module_name}

• Uses Vite's import.meta.glob for static imports
• Scans frontend/src/modules/*/config.ts
• Registers routes and sidebar entries
• Auto-updates on rebuild

• 🌙 Dark mode by default (Slate 950)
• 📱 Responsive design (Mobile-first)
• ⚡ Lucide React icons
• 🎨 Tailwind CSS styling
• 🧩 Recharts for data visualization

• Idle Memory: < 100MB RAM
• Startup Time: < 5 seconds
• API Response: < 100ms (most endpoints)
• Frontend Bundle: Optimized with Vite

journalctl -u copanel -f

nginx -t
systemctl restart nginx

# Check module structure
ls -la backend/modules/your_module/
# Ensure router.py exists
# Restart service
systemctl restart copanel

cd frontend
npm run build
# Refresh browser cache (Ctrl+Shift+Delete)

To contribute:

1. Fork the repository
2. Create a module in the appropriate modules/ folder
3. Follow the module structure guidelines
4. Test thoroughly
5. Submit a pull request

MIT License - See LICENSE file for details

• FastAPI Documentation: https://fastapi.tiangolo.com
• React Documentation: https://react.dev
• Vite Guide: https://vitejs.dev
• TailwindCSS: https://tailwindcss.com
• Recharts: https://recharts.org

For issues, questions, or suggestions:

• GitHub Issues: Create an issue in the repository
• Documentation: Check the README in each module folder

Built with ❤️ for Linux System Administrators