Follow-up to #127.
Summary
Consolidate scripts/setup/setup-linux-mshv.sh and scripts/setup/setup-linux-runner.sh into one Linux setup entry point, following the mode-based structure already used by scripts/setup/setup-windows-whp.ps1.
The unified script should support both:
- development-host setup for an existing Linux/MSHV NVX checkout; and
- hardened persistent GitHub Actions runner setup for Linux/KVM or Linux/MSHV.
Motivation
The Linux scripts currently duplicate package installation, Rust and cargo-nextest provisioning, version pins, host validation, and MSHV device setup. Keeping separate implementations increases drift risk and makes Linux behavior inconsistent with the single Windows setup entry point.
Proposed direction
Use the Windows script's interface as the model:
- make development-host setup the normal mode;
- add an explicit runner-only mode for Actions runner provisioning;
- require the backend selection where runner mode needs to distinguish KVM from MSHV;
- keep runner registration optional unless a runner name/token is supplied; and
- share common package, toolchain, virtualization, and validation functions between modes.
Choose one canonical Linux script name and either preserve compatibility wrappers temporarily or document the migration from both existing entry points.
Requirements
- Preserve development-host behavior from
setup-linux-mshv.sh:
- existing-checkout and OpenVMM submodule validation;
- Docker and Buildx installation/access for the developer;
/dev/mshv access and reconnect signaling;
- NVX build and MSHV dry-run validation;
--check-only, --skip-build, --workspace, and guest-bundle workflows.
- Preserve runner behavior from
setup-linux-runner.sh:
- KVM and MSHV backends;
- dedicated
nvx-runner service account;
- root-owned/read-only trusted toolchain and pinned
sccache;
- runner registration, labels, service configuration, migration, and check-only validation;
- no sudo or Docker access for workflow jobs;
- writable-state confinement to the runner work directory.
- Continue supporting Ubuntu through
apt-get and Azure Linux/Mariner through tdnf or dnf.
- Retain existing completion markers and meaningful exit behavior, or provide a documented compatibility transition.
- Avoid requiring an NVX checkout in runner-only mode.
- Update setup documentation, quality checks, and tests to reference the canonical entry point.
- Pass the repository's ShellCheck, shfmt, and targeted setup-tool tests.
Acceptance criteria
- One canonical Linux script can configure an Ubuntu or Azure Linux development host for MSHV.
- The same script can configure an Ubuntu or Azure Linux Actions runner for either KVM or MSHV.
- Development mode retains Docker/build/guest-bundle functionality.
- Runner mode retains the existing account, filesystem, service, and device-access hardening.
- Shared provisioning logic is implemented once rather than copied between modes.
- Documentation clearly distinguishes development-host mode from runner-only mode and includes examples for each.
Follow-up to #127.
Summary
Consolidate
scripts/setup/setup-linux-mshv.shandscripts/setup/setup-linux-runner.shinto one Linux setup entry point, following the mode-based structure already used byscripts/setup/setup-windows-whp.ps1.The unified script should support both:
Motivation
The Linux scripts currently duplicate package installation, Rust and cargo-nextest provisioning, version pins, host validation, and MSHV device setup. Keeping separate implementations increases drift risk and makes Linux behavior inconsistent with the single Windows setup entry point.
Proposed direction
Use the Windows script's interface as the model:
Choose one canonical Linux script name and either preserve compatibility wrappers temporarily or document the migration from both existing entry points.
Requirements
setup-linux-mshv.sh:/dev/mshvaccess and reconnect signaling;--check-only,--skip-build,--workspace, and guest-bundle workflows.setup-linux-runner.sh:nvx-runnerservice account;sccache;apt-getand Azure Linux/Mariner throughtdnfordnf.Acceptance criteria