Material Virtual Machine

Material Virtual Machine is a Material Design 3 rewrite of the Qt desktop front end for VirtualBox. It keeps the VirtualBox engine, COM/XPCOM contracts, machine models, action pools, and kBuild targets intact while moving the application-owned presentation toward one coherent Qt 6 design system.

Documentation: Material Virtual Machine documentation

Delivery map: roadmap · current handoff · changelog · native implementation authority

Install status: verified unsigned NSIS installers are published as GitHub releases (VirtualBox-7.2.97-Setup.exe); the Releases page is the authority for which release is newest and what commit it targets, and no tag is pinned in this file's prose. You can also build from source with the canonical VirtualBox prerequisites and commands.

The ceiling, stated before anything else: no virtual machine can start. The host hypervisor driver VBoxSup.sys is unsigned, 64-bit Windows will not load an unsigned kernel driver, and code signing is permanently prohibited for this project. It is a policy consequence, not a defect, and no installer change can resolve it. Only the machine's owner choosing to permit unsigned drivers moves it, and that decision has an owner outside this codebase. What this project delivers is the Material 3 presentation of the Manager, settings, wizards and tools — not a running guest.

Implementation status: the shared theme, style, language, persisted brand, native manager title bar, manager navigation rail, manager tab strip, manager-tool search card, command palette, appearance editor, full guided shared regex builder, four-scope tab manager, single-page settings shell, settings search field, and the notification-center search and keyboard-accessible notification rows are wired into the existing VirtualBox frontend. The shared style now gives stock Qt controls Material semantic colors, shape, state layers, focus treatment, disabled presentation, and bounded minimum anatomy across manager, settings, wizard, and runtime-owned pages. The responsive wizard shell now composes the real page stack, visible-step rail, bounded page card, and native action row; manager-tool and runtime shells remain in progress. The local history browser now restores validated notification and appearance/theme revisions through their owning services. Build and release claims below are deliberately bounded.

How much is not done, beside that list: the hand-maintained per-surface inventory in doc/md3/CompletenessInventory.md holds 91 rows — 33 Implemented, 18 Partial, 39 Not implemented, 1 justified N/A, from python tools/md3/count-inventory-rows.py run on 2026-08-16. The list above is the Implemented and Partial end of that inventory, not its whole. Which gates this project can run at all, which are blocked and by what, is doc/md3/LocalGates.md.

Contents

• Design package
• Runtime screenshots
• Architecture
• Build and prerequisites
• Verification boundaries
• CI and Pages
• Roadmap and handoff · changelog · capture matrix
• Contributing
• Security and license

Design package, native evidence, and implemented surfaces

Design package

The checked-in design/ directory is the authoritative review package for the rewrite. It contains five native-Qt reference prototypes, shared interaction data, C++/kBuild starter references, icons, and the implementation handoff.

Surface	Prototype
Virtual machine manager	Manager.dc.html
Machine settings	VM Settings.dc.html
Runtime window	Runtime Window.dc.html
Wizards	Wizards.dc.html
Manager tools and preferences	Managers.dc.html

Runtime screenshots

Screenshots in this section are reserved for captures from the built native application. Two different observations live here and an earlier version of this section ran them together, so they are now separated and each one is labelled with which build it came from.

• What this checkout's own build does: it does not reach the manager shell. The Windows runtime launch reaches the real executable and then stops at REGDB_E_CLASSNOTREG, because no VBoxSDS service is registered for this checkout and its VirtualBoxClient COM registration is therefore incomplete. No image of that failure is committed anywhere in this repository. A repository-wide search recorded in doc/md3/CaptureMatrix.md found none, so it is not counted as evidence and is not linked from any row. This paragraph previously said the capture was "retained in the session evidence"; that claim is withdrawn.
• Where the reached-and-photographed manager shell came from: a different build. One capture, taken at worktree tip cb9f573030e3f27d7b13314d90234e2b8de873c9 against an already-present installed %LOCALAPPDATA%\VirtualBox\app-7.2.97\VirtualBox.exe — not against this checkout's build and not against any published release asset — shows the manager shell rendered with no COM error. It is one image, from one build, in one environment. It does not generalise to any release, and it does not cancel the failure above.

The design thumbnail and static HTML previews do not count. The gallery will grow only with real manager, settings, wizard, tool, notification, and runtime captures from the rewritten build.

The capture contract and current COM/service evidence are maintained in doc/md3/RuntimeCapture.md. The full enumerated tracking table — every surface and state that must be captured, its current Captured/Not captured status, and its exact blocker where still open — is doc/md3/CaptureMatrix.md; that document is the authority for the current count, not this paragraph. Most rows remain open, blocked either by needing a running VM or an installed host service (kernel drivers, VBoxSDS) that this lane cannot provision, or simply not yet attempted.

Global Preferences and per-machine Settings now compose their existing page models inside a bounded Material selector, one selected page card, and a compact search/Basic/Expert header. An active query intentionally restores cross-page results. Global Preferences alone offers a collapsed, persisted language and appearance panel; Machine Settings no longer carries global controls. The shell is documented in doc/md3/SettingsShell.md, while the individual scheme, seed, density, typography, and display-brand controls remain documented in doc/md3/AppearanceSettings.md. Native visual evidence is still subject to the capture gate above.

MD3 widgets with stable keys also expose a bounded per-element appearance editor from their context menu and Shift+right-click. The editor persists seed, typeface, corner radius, scale, and weight overrides and has a reset path. Its live preview and editor-local regex search are live. The editor also saves and applies complete named themes (including element overrides), rejects malformed or out-of-range values transactionally, and returns focus after close; the complete Word-depth typography picker remains tracked as open design-coverage work.

The manager command palette is documented in doc/md3/CommandPalette.md. Ctrl+Shift+F is wired to live, category-grouped manager commands through a stable owner and command-id registry with Home/Machines/Media/Network/Cloud/Resources/Extensions destinations, action-pool enabled-state explanations, focusable unavailable rows, UIMd3Language-backed English/Cantonese/bilingual copy with independent funny-level refresh, exact handler-owned focus, bounded accessible results, and focus return; its native capture remains pending the COM registration gate.

Material colour roles are now generated from native HCT/CAM16 core palettes instead of the former HSL approximation. The compiled tonal-palette testcase covers 127 reference, gamut, contrast, and stability checks; implementation, failure bounds, and verification are documented in doc/md3/TonalPalette.md.

The frameless Windows manager title bar is documented in doc/md3/TitleBar.md. The 48-pixel header now presents a compact application mark/name, manager subtitle, command-palette pill, notification state, and icon window actions. Its real menu, window, palette, and notification paths preserve existing authority while the hidden legacy menu model opens on demand. Native snap, high-DPI, and bilingual captures remain part of the deferred runtime evidence matrix.

The complete production composition is documented in doc/md3/ManagerShell.md: a 48-pixel header, 48-pixel on-demand workspace strip, 92-pixel desktop rail with a compact searchable navigation action below 1000 logical pixels, destination heading with contextual action pills, and padded Machines chooser/workspace cards. The serial Windows gate rebuilt and linked UICommon and VirtualBox, then confirmed VirtualBoxVM was already up to date against that shared library; real native capture remains a separate runtime gate.

The first manager-tools slice is documented in doc/md3/ManagerTools.md. Extensions, Media, Network, Cloud, and VM Activity Overview now share one persistent Material plain-text/regex search and appearance card over their existing item views. It restores each view's original hidden rows, coalesces live model changes, keeps the original actions and models authoritative, and removes the duplicate Media search action from the embedded contextual toolbar. Bulk operations, export, Logs, detached manager windows, and native capture remain open.

The manager's 92-pixel navigation rail uses stacked icon-and-label destinations in the prototype order. Its buttons must select the existing UIToolType models, preserve expert-mode restrictions, open workspace tabs on demand, show keyboard focus, and reflect the active theme. Up/Down traversal includes the fixed Preferences destination, unavailable items explain the unmet condition, and bundled icon masks are recolored for the active Material role and display scale. A capture that cannot show those live behaviors is not accepted as GUI proof. The underlying UIToolsItem names and accessibility descriptions use stable md3.tool.* keys through the persisted Material language service, refreshing on English/Cantonese/bilingual and funny-level changes through a unique language connection while retaining the existing Qt translation listener fallback.

The manager tab strip is documented in doc/md3/TabNavigation.md. It delegates tab selection to the existing global-tools model, opens visited destinations on demand, migrates only the exact legacy generated seven-tab layout to one pinned available destination, persists groups/pins/current selection under a scoped VirtualBox extra-data key, keeps empty bulk-close queries safe, and exposes a searchable Move… into group… picker with member counts and an inline create-group path; the 48-pixel strip now reserves 48 px focusable New tab, Tab manager, More-tabs, and inline close targets. Overflow activation reveals the selected tab, active-tab close emits one final fallback state, and the group picker is screen-bounded and rejects hidden filtered results. A dedicated transparent child exposes only the real PageTab roles; the other accessible actions remain siblings. Strip chrome also offers bounded group creation and renaming plus a per-group Edit appearance… action while retaining the local search field. Keyboard context menus reuse the stable current tab so Shift+F10 exposes real tab-management actions; pointer chrome keeps its strip-level menu. Activating a member of a collapsed group temporarily reveals that tab without overwriting the group's collapsed preference. Ctrl+Shift+T opens four independent discovery scopes (current strip, group names, every individual group, and every registered window), each with its own full guided regex builder. Separate containing and inverse bulk-close fields require a reviewable, pinned-safe preview and re-resolve the model before closing. Drag reordering, dockable strip orientations, complete group lifecycle, settings/runtime adoption, tab-state history, and native capture remain open.

doc/md3/RegexBuilder.md documents the complete plain-text-first builder shared by every Material search field: guided literals, classes, anchors, groups, alternation and numeric quantifiers; raw PCRE2-compatible syntax and i/m/s/x flags; local sample matches and capture groups; copy/atomic JSON export; independent visible state; one-worker generation control; a 300 ms UI deadline; bounded inputs/results; focus return; and screen-bounded or menu-inline scrolling.

doc/md3/StockControlStyle.md documents the shared QProxyStyle bridge for the existing stock Qt controls. It applies the live semantic palette and typography to buttons, fields, choices, tabs, menus, lists, headers, sliders, scroll bars, progress, toolbars, status bars, and group-box frames while preserving their existing models, validation, accessibility roles, and action ownership. Dedicated VirtualBox-painted widgets remain separate rewrite lanes, and native visual proof remains deferred.

The existing notification center now has a Material 3 search field in its extended view. doc/md3/NotificationCentre.md documents plain-text and bounded regex filtering across real notification metadata while preserving critical-item and blocking-operation behavior, and retains non-blocking snapshots in a bounded searchable history model. The manager header's Notifications button opens that review surface and shows an unread marker. The history rows now support filtered selection, inversion, selected-read updates, and bounded JSON export. Clear history uses an app-owned destructive gate with the exact record count, two acknowledgements, a full-range slider, animated progress, Emergency exit/Escape, and focus return; the review surface also offers one bounded Undo last clear recovery snapshot. Legacy notification rows expose an accessible name, visible keyboard focus, and Enter/Return/Space details disclosure; pointer-only expansion is no longer required. The shared doc/md3/History.md journal records clear, restore, and later notification-change revisions in an isolated local Git repository when Git is available, with an atomic-file fallback. The full history browser is now reachable with Ctrl+H and from the command palette; it provides plain-text-first search with the anchored regex builder, action/date filters, bounded JSONL export, integrity verification, and a validated Restore notification and appearance/theme state actions for supported revisions. Surface-specific settings/runtime restore adapters, provider-authored rendering, bulk dismiss/delete, complete row selection/restore semantics, and native capture remain open lanes. This is not a claim that the legacy notification surface has been fully replaced. The modeless review surface now uses idempotent signal connections and one sigChanged() refresh path, avoiding callback multiplication after reopen and duplicate list rebuilds after model mutations.

The existing New VM, New virtual disk, clone, import, and export flows now compose an embedded Material 3 wizard shell around their real UINativeWizardPage stacks. doc/md3/WizardShell.md documents the two-card desktop layout, compact rail collapse below 720 logical pixels, hidden-page reconciliation, bounded page scrolling, translated page title, step summary, completion state, localized current/completed/upcoming step descriptions, named page stack, and accessible 48-pixel Back/Next/Finish/Cancel/Help actions while preserving validation/progress contracts. Cross-wizard tabs, full validation summary details, runtime accessibility-tree captures, and native runtime captures remain open.

The handoff requires accounting for all 69 archive entries. The maintained ledger is doc/md3/DesignCoverage.md, with its reproducible hash list in doc/md3/ArchiveManifest.sha256. Regenerate both with pwsh -NoProfile -ExecutionPolicy Bypass -File tools/md3/generate-design-coverage.ps1 after changing the design package.

Architecture and target ownership

Architecture

This is one VirtualBox frontend, not a parallel demo application.

• Manager: refactor UIVirtualBoxManager and UIVirtualBoxWidget visually while retaining UIActionPoolManager, UIChooser, UIToolPane, and their existing models and signals. UIMd3NavigationRail now presents the global tool selection while the original model remains the source of truth.
• Runtime: add Material chrome around UIMachineWindow and UIMachineView; do not replace guest display, capture, session, or multi-monitor ownership.
• Settings and wizards: host the existing UISettingsPage and UINativeWizardPage implementations in Material shells without bypassing validation, serializers, progress, or cleanup.
• Shared UI: place genuinely shared tokens, theme, style, search, language, notification, history, accessibility, and safe utility code in the UICommon boundary. Manager-only code belongs to VirtualBox; runtime-only chrome belongs to VirtualBoxVM.
• Bundled assets: the manager rail consumes the checked-in MD3 icon set through src/md3/UIMd3Icons.qrc, with a deterministic Qt standard-icon fallback if an individual resource cannot be loaded.
• Tabbed manager navigation: UIMd3TabStrip presents the global tools as browser-style tabs while preserving the existing UIToolType authority and using the shared UICommon extra-data persistence path.
• Persistence: use VirtualBox extra data and existing settings APIs. Do not introduce a second preferences database.

The target visual system is Qt 6 Material Design 3 with seed #6750A4, dark first-run presentation, comfortable density, a frameless platform-aware title bar, keyboard and screen-reader support, and preserved translations. The visual rewrite must not weaken hardening, authentication, destructive-action confirmation, or VM/session safety.

Build from source and local prerequisites

Build and prerequisites

VirtualBox is a large native project. Follow the canonical build instructions and the local coding guidance before attempting a full build.

For an external checkout, the supported shape is:

py -3 configure.py
kmk

For a narrower target after the environment is configured:

kmk -C src/VBox/Frontends/VirtualBox

The build requires a compatible compiler, Qt 6 development files, kBuild (kmk), platform SDKs, and the other dependencies selected by configure.py. Do not copy generated output or machine-local settings into the source tree; use LocalConfig.kmk for local overrides.

One-click Windows build and installer scripts

The repository root now carries the same supported Windows build path used by the package workflow:

build.bat
build.bat /s
build-installer.bat /s

build.bat bootstraps missing user-scoped dependencies, configures the native tree, and builds the runnable VirtualBox.exe payload. Without /s it offers one final choice to launch that payload; /s, --silent, or SILENT=1 keeps the entire run non-interactive. build-installer.bat runs the same path and then builds the single unsigned elevated NSIS installer (VirtualBox-<version>-Setup.exe plus SHA256SUMS.txt) that installs the complete host product -- VirtualBox Manager, VBoxSVC, the VBoxSDS service and its COM registration, the Guest Additions ISO, and the host kernel drivers when Windows accepts them. This project shipped a separate unsigned Squirrel.Windows package here until 2026-08-14; Squirrel was retired outright because it is a per-user file unpacker with no elevation and could not register COM, install VBoxSDS, or install kernel drivers at all -- see doc/installer/WindowsHostInstallerNSIS.md. Neither script ever publishes, tags, pushes, or invokes a signer.

Current CI status, stated honestly: the Windows package and release workflow this script mirrors previously failed at commit 9efa7f522c69f3ce1b99940d13e96d534ee2a0c3 (run 31731859854), getting through Qt setup, MSVC toolset selection, and the full build before failing in its own packaging self-check with STATUS_STACK_BUFFER_OVERRUN. That blocker has since been fixed: every non-draft v7.2.97-ci.* release from v7.2.97-ci.97 onward carries a real unsigned NSIS installer named VirtualBox-7.2.97-Setup.exe together with SHA256SUMS.txt. v7.2.97-ci.96, the first release ever published, is not one of them — it is the retired Squirrel.Windows package (Setup.exe, RELEASES, a .nupkg) and carries no VirtualBox-7.2.97-Setup.exe; ci.97 is the first NSIS release. Which release is newest, and what commit it targets, is answered by the Releases page and not by this file — no tag is pinned here, because each previous attempt to pin one was stale within days. Nothing on this page claims any of those installers has been downloaded, installed, or launched; the retraction at the head of CHANGELOG.md states that limit in full. See CHANGELOG.md for the fix history and HANDOFF.md for the full state summary. No local artifact produced on a warm, already-built tree is accepted as evidence that either script works from a genuinely clean checkout — only a passing run of that same CI job, or an equivalent from-empty local run, counts.

The helper is tools/build-windows.ps1. It keeps downloads in a user-local cache, verifies the pinned Windows SDK and WDK installer hashes, obtains Qt through aqtinstall, builds the documented NSIS 3.10 NSIS_CONFIG_LOG package from its pinned source (including the x86 zlib and PE-version prerequisites), materializes its pinned Unicode installer plugins, and reports the artifact path and SHA-256. The reusable source-build step is tools/prepare-nsis.ps1, and the dependency release refuses a cache that lacks its log-support marker. An unsigned installer can trigger an unknown-publisher or SmartScreen warning; that warning is expected and is disclosed rather than hidden.

Current verification boundary: the evidence below was built from exact settings-shell source commit 152327ec9fe04455de55def8bd8e943138b75737 on a Windows x64 development host, using MSVC 14.44, Windows SDK 10.0.26100.0, Qt 6.8.3 with the official qtscxml add-on, and the bundled kBuild executable. It is compile/link evidence, not a runtime or release claim.

Target	Local result	Completed (UTC-04:00)	Installed artifact SHA-256
UICommon	Exit 0, changed settings source compiled and linked	2026-08-09 14:55:25	BC308CC34B9C8D749E67C0C625159E23C5EB9067EBF1B3E472DAB26E6D342893
VirtualBox	Exit 0, dependency-current	2026-08-09 14:45:57	127314B61C157DB98DF75990A10AE76E6216B135F614193BB1876E81CBC1FC0B
VirtualBoxVM	Exit 0, dependency-current	2026-08-09 14:46:24	2B6075A37083CCA25AE2DAB113C3B20A1136F76E35F8F864A0F93ACD4AA13F22

The serial target commands used the repository's configured environment and checked UICommon, VirtualBox, and VirtualBoxVM separately. This proves the changed settings translation units compiled and linked, and that the manager and runtime targets remained dependency-current on that host. Full runtime manager capture remains blocked by the checkout's unregistered VirtualBoxClient COM runtime (REGDB_E_CLASSNOTREG); no mock screenshot is counted as GUI proof. CI-only correction f8c3bfffb55b8c8f0f0f884645afc1f0e99ade25 completed validation run 31330546183 and Pages run 31330546180 successfully; the deployed Home page and SettingsShell.md article returned HTTP 200 with the new content.

Verification boundaries and remaining runtime gates

Verification boundaries

Static inspection and the native build prove the design package, the 69-entry ledger, the shared MD3 theme/style integration, and the compiled VirtualBox target. The following remain open:

• the complete release packaging path;
• Qt widget, accessibility, keyboard, localization, and persistence tests;
• Windows frameless title-bar, DPI, snap-layout, and focus validation;
• manager, settings, wizard, manager-tool, notification, and runtime screenshot capture from a built artifact;
• installer, release, update, and signed/unsigned artifact verification.

When the toolchain is available, run the narrowest relevant gates first, then the full GUI target. Validation Kit and runtime testcase commands are documented in AGENTS.md; they are not represented as passed by this README.

Continuous integration and GitHub Pages

CI and Pages

This mirror contains MD3 validation and GitHub Pages workflows under .github/workflows/. Validation run 31330546183 and Pages run 31330546180 passed for CI-only corrective child commit f8c3bfffb55b8c8f0f0f884645afc1f0e99ade25 of settings-shell source commit 152327ec9fe04455de55def8bd8e943138b75737; the published landing page and SettingsShell.md article both returned HTTP 200. These are source-contract and static-site results, not proof that the native manager launched; the COM runtime boundary and real GUI capture remain open.

When publication work is added, it must build from the intended commit, keep artifact and test evidence separate, publish only verified outputs, and expose the documentation site from the repository homepage. A green static check must not be described as a successful GUI build or release.

Contributing to the native frontend

Contributing

Read AGENTS.md, CONTRIBUTING.md, the Qt coding section in doc/VBox-CodingGuidelines.cpp, the makefile guidance, and SECURITY.md before editing.

Keep changes narrow and tied to the real VirtualBox models and action pools. Do not add HTML, React, browser-engine, CDN, or network dependencies to the production frontend. Add new source files with the repository's standard headers and properties, update the relevant manual and changelog entries, run scm checks when available, and report every unrun gate and external blocker.

The canonical repository is SVN; this checkout is also mirrored on GitHub. Do not assume the GitHub mirror contains newer internal fixes. Commits, branches, tags, and publication should follow the repository owner's explicit workflow.

Security reporting and license

Security and license

Report vulnerabilities using the process in SECURITY.md, not through public issue details. VirtualBox is distributed under GPLv3 as shown in COPYING, with additional third-party license notices in THIRD_PARTY_LICENSES.txt.

Copyright (C) 2025 Oracle and/or its affiliates.