bmcgonag/incus-commander repository overview

⁠Incus Commander v0.3.2

A web-based management platform for Incus containers and virtual machines. Built with Vue 3, FastAPI, and PostgreSQL.

⁠Documentation

⁠Features

⁠Federation (Hub Mode)

• Hub/Provider architecture — designate a server as a federation hub, register providers with RSA keypair authentication and delegation JWTs
• Self-registration — providers register via API key handshake, receive hub public key + endpoint
• Provider manifests — providers expose resources, pricing, quotas, and image templates for hub aggregation
• Federated Instance CRUD — create, list, get, start/stop/restart, terminate instances across providers through the hub
• Federated Instance Migration — migrate instances between providers with step-based progress via background tasks (backup → stream through hub → import → cleanup)
• Template Catalog — aggregated image catalog across all providers with type (container/VM) and fingerprint
• Provider heartbeat — online/offline tracking with last_seen_at timestamps
• Pricing & Quotas — per-provider pricing (CPU/RAM/storage/GPU) and per-user quota enforcement
• Cost Estimates — live monthly cost display during instance creation
• Billing Reports — monthly cost breakdowns by user, provider, instance, and template; invoice generation with automated hub fee (3%) and provider payout calculation
• Instance Resizing — live CPU, RAM, and root disk resizing on running instances via hub delegation

⁠Feature Requests

I will always take Feature Requests, but understand the following:

• This is a community project, which means the community can contribute in many ways.
• This is a passion project for the open source community.
• Read the license.
• Don't send README spelling corrections only. Just let me know you have a spelling correction you'd like to see.
• I will work pull requests as I have time, and not faster.
• If you also used AI to help you add a feature, or fix a bug, understand YOU are responsible for making sure the AI only did what you asked, and that all existing tests pass, and any new feature or bug fix includes new API, UNit, andn / or End to End tests as apprpriate. They must all pass. You are responsible for updating the docs as appropriate as well.
• I do have a roadmap for new features and updates. Your features and ideas do not have to fit into that roadmap.
• I will work on feature requests if I feel they are useful or beneficial, and only in that case. If you want something I don't want to do, please feel free to create a fork, add your feature, and then do a pull request back to the project.
• Please note the license, and understand what it means for your projects built with this project included in it.

⁠Instance Management

• Create — containers and VMs from images with CPU/RAM/disks/profiles
• Edit — update description, CPU, memory, boot autostart, security nesting, profiles
• Static IP Assignment — set NIC, IPv4 address/subnet, and gateway on creation with cross-system conflict detection
• Start / Stop / Restart — lifecycle management
• Delete — with confirmation
• Console — browser-based terminal via WebSocket
• Snapshots — create, restore, and automatic retention pruning
• Backups — export/import individual backups
• Import backup as new instance — upload a backup archive to any connected system
• Scheduled Backups — cron-based automatic backups with compression (zstd/gzip/xz), retention count, and email alerts on failure
• Move/Copy — migrate instances between connected Incus systems with step-based progress via background tasks
• Assign to User — associate an instance with a specific tenant user

⁠Network Management

• Bridge networks — create and manage managed bridge networks
• OVN Networks — create OVN networks with parent bridge selection and custom IPv4 subnet (gated by role-based settings)
• Network list — view all networks across all connected systems with type badges

⁠Storage Management

• Storage templates — predefined volume configurations with size tracking
• Storage volumes — list all volumes across all systems, grouped by system and pool
• Move/Copy volumes — migrate storage volumes between systems via streaming export/import with step-based progress

⁠Multi-Tenant

• Tenant isolation — projects mapped to Incus projects per tenant
• Role-based access — three tiers: admin, tenant_admin, user
• User management — invite users via email (SMTP), registration toggle, per-tenant OIDC configuration

⁠Authentication

• Local auth — built-in username/password login; first user is admin
• OIDC SSO — authenticate via any OpenID Connect provider (Authentik, Keycloak, etc.), configurable per-tenant
• Registration — can be disabled by admin
• Two-Factor Authentication (TOTP) — admins can require TOTP-based 2FA for all local-auth users. Enrollment via QR code (otpauth:// URI), manual Base32 secret, and 8 single-use recovery codes. Admin override with per-user TOTP reset.

⁠Dashboard

• Live summary — all connected Incus systems, instances, tenants
• CPU/RAM gauges — per-system utilization with delta-based CPU percentage
• Network throughput sparkline — real-time bandwidth graph
• Tenant cards — instance counts per tenant
• Backup alerts — banner when scheduled backups fail
• Background task progress — polling-based step display for long-running operations

⁠Templates

• Instance templates — predefined CPU/RAM/disk/profiles for consistent deployments
• Image remote browsing — browse and pull images from remote servers

⁠System Administration

• Health checks — per-system readiness checks: API connectivity, certificate trust, Incus bridge existence, storage pool capacity, firewall driver detection
• Activity Logs — comprehensive audit trail with multi-select filters (action, username, system name)
• Settings — configurable permissions for snapshots, backups, OVN creation, and more
• Certificate management — generate client certificates from the UI
• Invitations — email-based user invitation system

⁠Tech Stack

⁠Quick Start

cp .env.example .env   # edit secrets
docker compose up --build -d
# Frontend: http://localhost:5173

The first user to register becomes the system administrator.

⁠Production

cp .env.example .env   # edit secrets
# edit the .env values for your site, then
docker compose -f docker-compose.prod.yml up -d

See the Installation Guide⁠ for full production configuration (secrets, OIDC, SMTP, reverse proxy).

⁠Roles

⁠LICENSE

AGPL v3