A web-based orchestration platform that automates the creation of custom Proxmox VE auto-installer ISOs and manages VM deployments through a premium dark-mode GUI and REST API.

Features

ISO Builder: Generate custom Proxmox VE 9.1.x auto-installer ISOs with pre-configured answers.toml
VM Deployment: Automated VM lifecycle management (create, start, stop, destroy) via Proxmox API
Build Pipeline: Visual build status tracking with real-time log streaming
VM Control Panel: Direct VM management with status monitoring
REST API: Full programmatic access to all orchestrator functions
Premium GUI: Sleek dark-mode interface with glassmorphism design

Architecture

┌─────────────────────────────────┐
│     Frontend (Vanilla JS)       │
│  Dark Mode Dashboard + Forms    │
├─────────────────────────────────┤
│     FastAPI Backend (Python)    │
│  REST API + Static File Server  │
├──────────┬──────────────────────┤
│ ISO      │ Proxmox VE API      │
│ Builder  │ Client (httpx)      │
└──────────┴──────────────────────┘
         │              │
    ┌────┴────┐   ┌────┴────────┐
    │ xorriso │   │ Proxmox VE  │
    │ PVE ISO │   │ Host API    │
    └─────────┘   └─────────────┘

Quick Start

Prerequisites

Python 3.11+
xorriso (for ISO manipulation)
proxmox-auto-install-assistant (from Proxmox repos)
Proxmox VE API token (see Configuration)

Install & Run

# Clone
git clone ssh://gitea@git.theta42.com:2222/nova/sovereign-orchestrator.git
cd sovereign-orchestrator

# Install dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run
uvicorn app.main:app --host 0.0.0.0 --port 8888

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

Production Deployment

# Run as root on the target LXC container
sudo bash setup.sh
sudo systemctl start sovereign-orchestrator

Configuration

Proxmox Credentials

Create ~/.proxmox-credentials:

PROXMOX_HOST=https://your-pve-host:8006
PROXMOX_TOKEN_ID=user@pam!tokenname
PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Environment Variables

Variable	Default	Description
`PROXMOX_HOST`	(from credentials file)	Proxmox VE API URL
`PROXMOX_TOKEN_ID`	(from credentials file)	API token ID
`PROXMOX_TOKEN_SECRET`	(from credentials file)	API token secret
`ISO_STORAGE_PATH`	`/var/lib/vz/template/iso`	Path to ISO storage
`DEFAULT_NODE`	`dl380-0`	Default Proxmox node
`DEFAULT_VMID`	`900`	Default VM ID for deployments

API Reference

System Status

GET /api/status

ISO Generation

POST /api/generate-iso
Content-Type: application/json

{
  "fqdn": "pve.example.com",
  "keyboard": "en-us",
  "country": "us",
  "timezone": "America/New_York",
  "mailto": "admin@example.com",
  "root_password": "secure-password",
  "root_ssh_keys": ["ssh-rsa AAAA..."],
  "network_source": "from-dhcp",
  "filesystem": "ext4",
  "disk_list": ["sda"]
}

VM Deployment

POST /api/deploy
Content-Type: application/json

{
  "vmid": 900,
  "node": "dl380-0",
  "cores": 4,
  "memory": 8192,
  "disk_size": "64G"
}

Build Status

GET /api/builds
GET /api/builds/{build_id}

VM Control

GET  /api/vm/{vmid}/status
POST /api/vm/{vmid}/start
POST /api/vm/{vmid}/stop

ISO Listing

GET /api/isos

Project Structure

sovereign-orchestrator/
├── app/
│   ├── __init__.py
│   ├── main.py            # FastAPI application & routes
│   ├── config.py           # Configuration management
│   ├── models.py           # Pydantic data models
│   ├── proxmox_client.py   # Proxmox VE API client
│   └── iso_builder.py      # ISO generation logic
├── static/
│   ├── index.html          # Single-page application
│   ├── style.css           # Premium dark-mode styles
│   └── app.js              # Frontend application logic
├── setup.sh                # Production deployment script
├── requirements.txt        # Python dependencies
└── README.md               # This file

License

Proprietary - Theta42