Skip to content

setup: unify Linux development-host and runner bootstrap scripts #128

Description

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions