Incus Commander v0.7.5-beta

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

Documentation

Guide	Description
Installation	Setup, configuration, production deployment, connecting Incus systems
API Reference	Full API endpoint documentation with auth requirements
Admin Guide	System administration: multi-tenant, users, OIDC, systems, templates, notification channels
Tenant Admin Guide	Tenant-scoped management: users, templates, storage, OIDC
End User Guide	Creating and managing instances, attaching storage, root console, notifications
Smartbar Guide	Keyboard action runner (command palette): hotkeys, switches, and the full command reference

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

Notifications & Status Alerts

• Strictly opt-in — per-user rules with one-click presets; nothing is broadcast and no environment alert is sent unless you subscribed to its category
• In-app inbox — a header bell with an unread badge, a filterable list (category, severity, system, resource, read/unread, date), CSV export, and server-side read state that syncs across devices
• Own-action receipts — the result of your own backups, copies, moves and imports is always recorded for you, independent of subscriptions
• Pop-up alerts — environment alerts appear as toasts as the app polls and fade after 7 seconds (the alert itself stays in the list and the bell); own-action results keep their faster pop-up
• Threshold alerts — a 60-second evaluator for instance- and host-level CPU/RAM/disk/disk-free, with consecutive-check gating, per-episode coalescing, a configurable re-alert interval and optional "resolved" notices
• Host health alerts — the readiness checks (API, certificate, bridge profile, storage pools, firewall) run on their own slower loop (default every 5 minutes) and raise one host.health_failed episode per failing host, with a resolved notice when it clears
• Host Health icons — pass/warn/fail status at a glance on the Systems cards, the Systems Dashboard cards and the dashboard's Systems list, read from the persisted background verdict (zero extra Incus calls; instance cards deliberately carry none)
• Lifecycle & reachability — an Incus lifecycle event stream (start/stop/restart/delete, cluster-member dedupe, unexpected-stop detection) plus one-per-outage host up/down alerts
• Global policy — master switch, minimum severity, quiet hours (deferred, never dropped), and default delivery channels
• Eleven delivery connectors — webhook, email, Discord, Slack, Microsoft Teams, Telegram, Matrix, Rocket.Chat, Gotify, ntfy and Pushover, drained by an outbox dispatcher with exponential-backoff retries and per-channel rate limiting
• Admin Channels UI — create, test, edit and delete channels from System Settings; secrets are encrypted at rest and write-only

Smartbar (Keyboard Action Runner)

• Command palette — a configurable per-user hotkey opens a fuzzy-filterable action list
• Direct actions — lifecycle, console, storage, network, image, profile, host and cluster actions, with -c/-h target switches and -? help
• Recents, favorites and history — a curated empty state, pinned commands, and ↑/↓ recall

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
• Graphical Console (VGA/SPICE) — stream a VM's display into a full-screen browser canvas over WebSockets (VMs only; containers are greyed out)
• Clone — duplicate an instance on the same host
• 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
• Per-instance firewall — port forwards (proxy devices) and allow/deny access rules backed by per-instance network ACLs

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

Profiles & Clusters

• Profiles — create, view, edit and delete Incus profiles with NIC, GPU, USB and TPM devices; available GPUs are listed from host resources
• Clusters — bootstrap an Incus cluster from a system, add/remove members, and view per-member health (status, database/quorum)

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
• Image download manager — a floating panel with live progress for long downloads; upload local ISO images to a system

System Administration

• Health checks — per-system readiness checks: API connectivity, certificate trust, Incus bridge existence, storage pool capacity, firewall driver detection; also run on a background loop that drives the host health alerts
• 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

Layer	Technology
Frontend	Vue 3, Pinia, Vue Router, Ant Design Vue 4
Backend	FastAPI, asyncpg, PyJWT, httpx, croniter
Database	PostgreSQL 16
Auth	OIDC + local (bcrypt, PyJWT)
License	AGPL v3

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

Role	Description
user	Regular user — manages own instances and attached storage
tenant_admin	Tenant-scoped admin — manages users, templates, OIDC within their tenant
admin	Global admin — full system access, tenant CRUD, all configuration, settings