mfconsole/kvm-manager repository overview

⁠MFConsole

MFCloud Console is the control plane for the MFCloud platform — an enterprise KVM hypervisor manager. One image runs the web console, Celery worker, and beat scheduler (selected by command: in the shipped compose files). It manages VM lifecycle and live migration, Ceph/LINSTOR/ZFS storage, OVN networking, Kubernetes clusters, and multi-tenant RBAC, with optional HA via Patroni/TimescaleDB.

Public beta. Runs on the Free edition out of the box (2 nodes / 10 VMs, no license key needed) — paste a license key in Settings → Edition & License later to unlock higher caps and paid features (HA, S3 backup, multi-tenant, LDAP, and more).

⁠Deploy MFConsole — step by step

1. Get the deploy files from the image itself. docker create pulls the image if you don't already have it, then this copies the compose bundle out of it:

docker pull mfconsole/kvm-manager:latest
id=$(docker create mfconsole/kvm-manager:latest)
docker cp "$id":/app/deploy-files ./mfconsole
docker rm "$id"
cd mfconsole

Running Podman instead of Docker? Same commands, podman in place of docker (fully-qualify the image so Podman doesn't need to prompt for a registry):

podman pull docker.io/mfconsole/kvm-manager:latest
id=$(podman create docker.io/mfconsole/kvm-manager:latest)
podman cp "$id":/app/deploy-files ./mfconsole
podman rm "$id"
cd mfconsole

This gives you docker-compose.yml, compose.prod.yml, install.sh, setup.sh, Caddyfile, .env.example — the actual stack definition. Pulling the image alone never gives you these; the image only holds app code, not the orchestration files, which is why nothing was "installing."

2. Run the installer:

./install.sh

This creates .env, generates secrets (SECRET_KEY, INTERNAL_SECRET, DB_PASS, admin password), auto-detects your host's LAN IP for CONTROL_PLANE_IP, pulls the image, and brings up the single-node profile (db, redis, linstor-controller, caddy, app-1, worker, beat, watchtower). It auto-detects Docker or Podman on the host — pass --engine docker or --engine podman to force one if both are installed.

3. Verify it came up:

docker compose ps                                  # or: podman compose ps
docker compose logs -f app-1   # wait for "Application startup complete"

4. Log in: https://<CONTROL_PLANE_IP>/ — accept the self-signed cert warning, login admin / mfpro (forced password change on first login).

⁠Prerequisites to double check first — this is the most common reason nothing runs

• Docker (Compose v2 plugin) or Podman — docker compose version must work (not the old docker-compose v1 binary), or podman compose version / podman-compose --version for Podman.
• A Linux host (Rocky/Debian) — install.sh is bash, won't run on Windows directly.
• 4 vCPU / 8 GB RAM minimum.

Need compute nodes too? Download the MFConsole Node ISO — the hypervisor image your KVM hosts boot from — at https://mfcloud.io/download.html⁠

⁠What's New

0.46.0.0 (2026-09-16)

Bug fixes

• Installer hardening from a live customer incident. The console's task-queue backend (redis) could die silently — no error, no crash log — hours into a clean run, on a host with plenty of memory free. Root cause: the kernel's default memory-overcommit heuristic refusing a routine background-save fork(), exactly as redis's own startup warning describes. install.sh now checks and fixes vm.overcommit_memory on the host before starting the stack. Existing installs aren't affected until reinstalled/updated to this version.

0.45.11.0 (2026-09-16)

Changes

• Wide tables and panels are now capped to a comfortable reading width on large/ultrawide displays instead of spreading values across the full screen.
• Toast notifications now meet real contrast standards for every severity, hold errors on screen longer with a dismiss button, and announce themselves to screen readers.
• One consistent set of warning/critical thresholds across the console (tenant quotas, IP pools, network latency) instead of several different thresholds that had quietly drifted apart.
• OVN Central's Reachable indicator now reflects real network latency instead of always showing green.

Bug fixes

• VM Summary was reporting a VM's balloon-allocated RAM as "used" RAM, reading roughly 100% on every VM permanently. Now matches the Monitor tab.
• Alarm titles were nearly invisible in light theme. Fixed.
• Two different systems for identifying a VM/container's OS disagreed with each other. Unified onto one, with a couple of missing distros added.

0.45.6.0 – 0.45.10.0 (2026-09-09 to 2026-09-16)

New features

• Two-factor authentication (TOTP) for local accounts. Self-service enrollment from the account menu (QR code + 10 recovery codes), or make it mandatory platform-wide from Settings (off by default — existing installs unaffected until an admin opts in). Per-account exemption for break-glass admin accounts. A 10-angle hardening review pass closed an SSO/LDAP login-path MFA bypass and a recovery-code double-use bug before wide use — full detail in CHANGELOG.md 0.45.6.1.
• Cluster Benchmarks. New Super Admin-only tab: run real storage (fio), compute (sysbench), and network (iperf3) load tests directly against hypervisor node hardware, dispatched through the same per-node Celery queue every other node-targeted action uses. Includes a pre-run safety guardrail (checks live VM count, confirms before load-testing a host that's in use), historical trend charts + CSV export, recurring schedules with automatic regression alerting, and storage targets beyond local paths — ZFS pools, LINSTOR/DRBD resources (hard-blocked if a VM disk is attached), and Ceph pools via rados bench. Four bugs found running against real hardware (fio JSON parsing, a firewalld port range, an asyncio event-loop misuse, rados bench field-name mismatch) fixed in 0.45.7.4.
• Console-wide icon refresh. Replaced ~180 emoji used as icons across every JS module and 30 templates with one consistent inline-SVG icon set (menus, modals, toasts, the inventory tree) — renders identically across OSes, unlike the old emoji glyphs.
• Summary dashboard redesign. KPI cards now escalate color with real severity instead of a fixed color regardless of how bad things get; three mostly-empty donut widgets replaced with one Fleet Status line that expands into the actual alert text when something's wrong.
• Datastore list now shows live capacity (bar + percentage + free GB per datastore, one windowed query, no N+1). Settings gets one page-level save bar with dirty tracking, replacing two identically- labeled buttons that silently saved unrelated fields together.

Bug fixes

• Compute nodes updated by the console's own automatic sync could stay flagged "needs repair" forever, even once fully up to date. Fixed.
• The Software Update panel collapsed four distinct states into "up to date" / "update available" — now reports "ahead of registry" and "check failed" accurately.
• A failed datastore fetch rendered as an empty table instead of a visible error with Retry.

Full per-version detail (0.45.6.0 through 0.45.10.0) is in mfcloud-master/CHANGELOG.md.

0.45.5.3 (2026-09-08)

Bug fixes

• Compute nodes updated by the console's own automatic sync could stay flagged "needs repair" forever, even once fully up to date. Only the manual Repair Worker button was recording the version it pushed; the automatic path now does the same.

0.45.5.2 (2026-09-08)

Bug fixes

• A healthy Ceph cluster could show as unreachable on the dashboard. Newer Ceph releases report health in a different shape than older ones; the monitor now recognizes both. The cluster itself was healthy the whole time — this only affected what the dashboard displayed.

0.45.5.1 (2026-09-08)

Bug fixes — caught in review of 0.45.5.0's new AI Assistant features before they saw wider use.

• A long AI Assistant conversation could permanently break mid-session if automatic summarization landed at the wrong point. Fixed so summarization can never split an in-progress action.
• A message sent at the exact moment a conversation was being summarized could silently disappear. Fixed.
• The "Explain this task" shortcut could bypass an organization's configured AI usage ceiling. Now counted against the same monthly limit as the main chat panel.
• The GPU-reservation fix below could, in a narrow timing window, clear a different VM's GPU assignment instead of only the failed one's. Fixed to only ever release its own reservation.

0.45.5.0 (2026-09-08)

New features

• Per-tenant AI Assistant usage tracking, with an optional monthly spend ceiling. Every conversation now logs its token usage; admins can optionally cap monthly spend per tenant from Settings, with a running total visible to the tenant.
• Long AI Assistant conversations now compact automatically instead of growing without bound.
• IPv6 groundwork in the software-defined networking layer — foundation for dual-stack tenant networks, not yet exposed in any provisioning flow.

Bug fixes

• A failed VM creation could permanently strand a reserved GPU, recoverable only by retrying under the exact same VM name. Fixed, with a new admin option to manually release a stuck GPU reservation.

0.45.4.1 (2026-09-06)

Bug fixes

• A node-version-mismatch check shipped in 0.45.4.0 (below) never actually detected anything on a real multi-node deployment. Caught and fixed immediately, verified against the live fleet before wider use.

0.45.4.0 (2026-09-05)

New features

• Compute nodes now report their own software version on every heartbeat. The Hosts table shows a needs repair badge — click it to run Repair Worker directly — on any node whose version doesn't match the console's, instead of having to infer it from release notes. Every already-enrolled node shows this badge once, harmlessly, until its first Repair Worker run under this release.

0.45.3.7 (2026-09-05)

Bug fixes

• The new HA restore panel (below) could fail to stop/start services on some deployments. A hardcoded internal file reference didn't account for every install layout. Fixed before this saw wide use.

0.45.3.6 (2026-09-05)

New features

• Control-plane restore is now reachable from the out-of-band HA Manager (:9444 on HA installs) — list backups and trigger a full restore even with the console app itself down.

0.45.3.5 (2026-09-05)

Bug fixes

• Every control-plane backup's nightly restore-verification was failing (the backup itself was fine — only the verification step was broken). The console's database uses TimescaleDB, which needs its own restore mode around a standard pg_restore; that's now applied everywhere this console restores that database, including the documented DR procedure.

0.45.3.4 (2026-09-05)

Bug fixes

• Cloud backups (VM backups and control-plane backups) failed against Backblaze B2 with connection errors. A default HTTP behavior in the AWS S3 client library isn't compatible with B2's S3-compatible API. Fixed — AWS and MinIO users are unaffected either way.

0.45.3.3 (2026-09-05)

Bug fixes

• This image had no pg_dump/pg_restore — nightly control-plane backups silently failed. Missing from the image's packaging since 0.45.3.0; now installed.
• The DR restore helper (scripts/cp_restore.py) was missing from the image entirely. Now included.

0.45.3.2 (2026-09-05)

Critical fix — 0.45.3.0 broke every compute node's worker service. A missing-dependency bug crash-looped mfcloud-worker on every enrolled hypervisor node from the moment it updated to 0.45.3.0 — VM/container create, power, and migration silently got stuck at "Queued" fleet-wide, with the Queue Registry showing every node Offline. If you updated to 0.45.3.0 or 0.45.3.1 and see this, update to 0.45.3.2 and use Repair Worker on any node still stuck.

0.45.3.1 (2026-09-04)

Bug fixes

• The LXC Marketplace catalog stopped refreshing. TurnKey's mirror started rejecting the app's default HTTP User-Agent with a 403; requests now send a browser-like one. This also fixes TurnKey appliance installs, which were silently broken by the same cause.

0.45.3.0 (2026-09-04)

Opens the 1.0 GA line: full audit-trail coverage for identity/tenancy changes, and the first real control-plane disaster-recovery mechanism.

Security

• Every user/role/tenant change is now audited. Creating or deleting a user, granting a role, resetting a password, and all tenant lifecycle actions now write an audit-log entry — answering "who changed this, and when" for every identity/tenancy mutation, not just logins.

New features

• Automated, verified nightly control-plane backups. The console now backs up its own database and configuration (not just your VMs) to your configured S3 target every night, encrypted the same way VM backups already are. Each backup is proven restorable by actually test-restoring it into a throwaway database — not just checking the backup job exited cleanly. Manage it from Settings, with history and an on-demand "run now" button.

0.45.2.3 (2026-09-02)

Security hardening pass on the WireGuard Home VPS Relay feature introduced in 0.45.2.2, completed before any relay was used in production.

Security

• WireGuard private keys no longer transit the console's backend — they never leave the box that generated them.
• Removing a paired chassis now properly revokes its access on the relay, instead of leaving it able to reconnect.
• Relay/chassis details are now restricted to users with network-management permission, scoped to their tenant.
• The container health-check endpoint added in 0.45.2.2 is now loopback-only and no longer echoes internal error detail to callers.

Bug fixes

• Removing and re-adding a chassis could hand out a tunnel address already in use by another chassis, silently breaking its connection. Fixed, with a database-level guard against it recurring.
• A relay/chassis health check that failed at the network level no longer leaves the console showing a stale "Active" status indefinitely.

0.45.2.2 (2026-08-31)

New features

• Home VPS Public IP Relay. Give a home-lab hypervisor behind CGNAT (no public IP) a stable public presence by pairing it over WireGuard with a small relay VPS — set up and paired automatically from the console, no manual WireGuard configuration required.

0.45.2.1 (2026-08-31)

Fresh installs (empty database, no prior tables) crashed on every startup — core/schema.py created some tables' extra columns before the tables themselves existed. Existing deployments were unaffected.

Bug fixes

• lxd_containers.crs_last_migrated_at was added ~194 lines before CREATE TABLE IF NOT EXISTS lxd_containers itself, so a brand-new database hit UndefinedTable: relation "lxd_containers" does not exist on first boot and never came up. Moved the column-add to after the table creation.
• The Home VPS Relay feature's relays/relay_chassis tables were missing their CREATE TABLE IF NOT EXISTS entirely — same class of fresh-install gap. Added alongside the schema's other tables.

0.45.2.0 (2026-08-30)

GPU utilization and VRAM on the Host Monitor tab (NVIDIA and Intel), a new llama.cpp AI Assistant backend for GPU-accelerated local inference, and a fix for Windows VM deploys that could fail outright on some hypervisor builds.

New features

• GPU utilization and VRAM on the Host Monitor tab, alongside CPU/RAM/Disk/Network — NVIDIA and Intel GPUs both supported. Host-level only: a GPU passed through to a VM is invisible to the host by design.
• New AI Assistant backend: llama.cpp. SYCL-accelerated for Intel GPUs, alongside the existing Claude and Ollama backends — measured roughly 8x faster token generation than Ollama on the same card and model (3.9 → 32.3 tok/s). Both backends can run at once; pick per chat session.
• CPU/RAM now get CUR/AVG/MAX and Pause/Resume on the VM and Host Monitor tabs, matching what Network already showed.
• The AI Assistant panel can dock to the right edge as a fixed sidebar instead of only floating over the page.

Bug fixes

• Windows VM deploys could fail outright on some hypervisor builds. The boot disk now attaches to a SATA/AHCI controller — Windows has shipped an inbox driver for it since Vista — instead of a SCSI chip some QEMU builds don't compile in. No virtio-win.iso driver-load step needed either way.
• A brief database hiccup could make a network or security-group change silently fail to apply, with the console still showing it as applied. Fixed, and the last known-good state is now cached so a blip can't redirect where writes go at all.
• The IaC/Terraform API rejected VM-create requests that included a GPU, and silently ignored a requested tenant assignment. Both fields are now accepted correctly.

0.45.0.1 (2026-08-28)

A packaging bug in 0.45.0.0 could leave compute nodes unable to come back online after updating.

Bug fixes

• Compute nodes could get stuck unreachable after updating to 0.45.0.0. A file the new HA-Ready fix (below) depends on was missing from the package pushed out to nodes, so the node-side worker service failed to start and the console lost contact with the node until this fix. If you updated to 0.45.0.0 and a node still shows unreachable after updating to this version, use Repair Worker on that host to resync it.

0.45.0.0 (2026-08-27)

A VM HA badge that could read "safe to fail over" when a real incident would have refused to move the VM, plus a license expiry warning so a key doesn't lapse silently.

Bug fixes

• The HA-Ready badge could tell you a VM was safe to fail over when it wasn't. It judged "HA-Ready" from storage type and survivor count alone — it never checked whether the host actually had an iDRAC/BMC configured. The failover engine itself always got this right: a non-Ceph VM on a BMC-less host is skipped during a real failover, since there's no way to confirm the dead host is actually powered off first. Only the badge was lying, and an operator would have found out mid-incident. It now shows HA-Degraded instead of green wherever a real failover would refuse to act. A live audit of the production fleet found no VM currently in that state.
• ZFS cross-host replication could be pointed at a target pool that wasn't empty, which force-rolls-back the destination to match the incoming stream on the first run — silently destroying whatever was already there, including a live VM's disk. Creating a schedule now checks the target first and refuses if it's already in use. Leftover replication snapshots are also pruned automatically now instead of accumulating on both ends forever.

New features

• License expiry countdown. A top banner appears from 14 days out, with a shortcut straight to Manage License. Perpetual keys never warn; expiry only reverts to Free-tier caps, existing VMs and nodes keep running.

Also recently shipped — GPU-as-a-Service reaching SR-IOV and Kubernetes, an OVN-native load balancer for VMs, OVN north-south routing (gateway/NAT/HA), and LXD containers reaching quota, backup, migration and load-balancing parity with VMs. Full detail on all of it:

→ Full version history: https://mfcloud.io/changelog.html⁠

Full docs: mfcloud.io/docs · Pricing: mfcloud.io/pricing.html · Community: forum.mfcloud.io

***** ANY QUESTION PLEASE REACH OUT TO [email protected]⁠ *****