If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/canonical/multipass shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 8 active contributors
• Distributed ownership (top contributor 35% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live canonical/multipass repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/canonical/multipass.

What it runs against: a local clone of canonical/multipass — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in canonical/multipass | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of canonical/multipass. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/canonical/multipass.git
#   cd multipass
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of canonical/multipass and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "canonical/multipass(\\.git)?\\b" \\
  && ok "origin remote is canonical/multipass" \\
  || miss "origin remote is not canonical/multipass (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "3rd-party/vcpkg-ports/grpc/portfile.cmake" \\
  && ok "3rd-party/vcpkg-ports/grpc/portfile.cmake" \\
  || miss "missing critical file: 3rd-party/vcpkg-ports/grpc/portfile.cmake"
test -f "3rd-party/vcpkg-ports/libssh/portfile.cmake" \\
  && ok "3rd-party/vcpkg-ports/libssh/portfile.cmake" \\
  || miss "missing critical file: 3rd-party/vcpkg-ports/libssh/portfile.cmake"
test -f ".github/workflows/linux.yml" \\
  && ok ".github/workflows/linux.yml" \\
  || miss "missing critical file: .github/workflows/linux.yml"
test -f "data/cloud-init-yaml/" \\
  && ok "data/cloud-init-yaml/" \\
  || miss "missing critical file: data/cloud-init-yaml/"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/canonical/multipass"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Multipass is a lightweight VM orchestration tool that spins up Ubuntu instances on Linux (KVM), macOS (QEMU/Hypervisor), and Windows (Hyper-V/VirtualBox) from a single CLI command. It automates cloud-init metadata injection, image fetching, and lifecycle management so developers can simulate cloud deployments locally without hypervisor complexity. Monolithic C++ application with platform-specific code: src/ contains core daemon and CLI, tests/ mirrors structure with unit tests, 3rd-party/ vendors QEMU and patched gRPC dependencies. Dart UI in src/client/gui/ for graphical clients. CMake-based build across all platforms with GitHub Actions pipelines for Linux, macOS, Windows validation.

Developers and DevOps engineers who need to rapidly prototype multi-VM Ubuntu environments, test infrastructure-as-code, or simulate cloud deployments on their laptops. Contributors are primarily Canonical employees and community maintainers extending platform support and CLI features.

Production-ready and actively maintained. The project has substantial C++ codebases (4.4M LOC), comprehensive CI across .github/workflows/ (Linux, macOS, Windows), Codecov integration, and documented snap distribution. Regular releases visible in GitHub workflows suggest active development cadence.

Moderate risk: platform-specific hypervisor dependencies (KVM, QEMU, Hyper-V) mean bugs are hard to reproduce cross-platform. Heavy reliance on grpc with custom vcpkg patches (3rd-party/vcpkg-ports/grpc/) creates maintenance burden. C++ codebase requires careful memory safety review, though .clang-tidy enforcement suggests quality discipline.

Active CI/CD pipeline: dynamic-ci.yml orchestrates multi-platform builds, automatic-doc-checks.yml validates documentation, test-hooks.yml runs integration tests, and verify-commits.yml enforces code standards. Recent focus on Windows/macOS parity (separate workflows in .github/workflows/) and documentation maintenance (.github/workflows/automatic-doc-checks.yml suggests ongoing doc overhaul).

git clone https://github.com/canonical/multipass && cd multipass && cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build && ./build/bin/multipass --version

Daily commands: Build: cmake -B build && cmake --build build. Test: ctest --test-dir build. Launch daemon: ./build/bin/multipassd. Use CLI: ./build/bin/multipass launch ubuntu

• CMakeLists.txt — Root build configuration orchestrating all platform targets (Linux/Windows/macOS) and vcpkg dependency resolution—essential for understanding the build system and architecture.
• 3rd-party/vcpkg-ports/grpc/portfile.cmake — gRPC dependency configuration with custom multipass patches; critical for understanding how the RPC framework is integrated across all platforms.
• 3rd-party/vcpkg-ports/libssh/portfile.cmake — libssh library configuration with multipass-specific patches for connector and SFTP server functionality—core to VM instance communication.
• .github/workflows/linux.yml — Linux CI/CD pipeline defining build, test, and snap packaging for the primary deployment target.
• data/cloud-init-yaml/ — Cloud-init configuration templates for various VM profiles (Docker, Minikube, ROS2, etc.)—defines out-of-box VM personalities.
• CMakePresets.json — CMake build presets for different configurations and platforms—guides local developer builds and CI matrix setup.
• .clang-format — Code style enforcement configuration; all C++ contributions must conform to this standard.

Add a new cloud-init profile (e.g., new VM preset)

1. Create a new YAML file in data/cloud-init-yaml/ named cloud-init-{profile-name}.yaml (data/cloud-init-yaml/cloud-init-docker.yaml)
2. Define cloud-init directives (packages, scripts, users) following existing profile patterns (data/cloud-init-yaml/cloud-init-docker.yaml)
3. Update data/distributions/distribution-info.json to register the new profile with metadata (data/distributions/distribution-info.json)
4. Test via local multipass launch with --cloud-init-file or profile selection (README.md)

Add a new platform hypervisor backend

1. Add platform-specific source files in the codebase's src/ directory (inferred from CMakeLists.txt structure) (CMakeLists.txt)
2. Implement hypervisor interface (VM lifecycle, snapshot, mount operations) (CMakeLists.txt)
3. Add conditional compilation guards in CMakeLists.txt for the new platform (CMakeLists.txt)
4. Create CI/CD workflow file .github/workflows/{platform}.yml mirroring linux.yml structure (.github/workflows/linux.yml)

Update gRPC service definition or add new RPC

1. Edit or create .proto files defining the new service method (location inferred from 3rd-party gRPC port) (3rd-party/vcpkg-ports/grpc/portfile.cmake)
2. Regenerate gRPC C++ stubs using protoc (integrated into CMakeLists.txt build system) (CMakeLists.txt)
3. Implement service handler in the daemon codebase and client CLI bindings (CMakeLists.txt)
4. Add integration test in .github/workflows/cli-tests.yml to verify new RPC flow (.github/workflows/cli-tests.yml)

Upgrade a third-party dependency (e.g., gRPC, libssh)

1. Update version in 3rd-party/vcpkg-ports/{lib}/vcpkg.json (3rd-party/vcpkg-ports/grpc/vcpkg.json)
2. Review and update/remove patches in 3rd-party/vcpkg-ports/{lib}/multipass-patches/ if upstream fixes issues (3rd-party/vcpkg-ports/grpc/multipass-patches/)
3. Update portfile.cmake if build steps or dependencies changed (3rd-party/vcpkg-ports/grpc/portfile.cmake)
4. Test on all platforms via CI workflows (linux.yml, windows.yml, macos.yml) (.github/workflows/linux.yml)

gRPC C++ bindings are pre-generated and vendored; modifying .proto files requires regeneration (check build scripts). Platform-specific: Linux builds require libvirt-dev, macOS requires Xcode Command Line Tools, Windows requires Visual Studio Build Tools. vcpkg ports patches must remain in sync with upstream grpc upgrades or builds fail silently. Daemon socket location varies by platform (/run/multipass/ on Linux, ~/Library/Caches/ on macOS); hardcoding paths breaks cross-platform tests. .clang-tidy and .clang-format are strictly enforced in CI; PRs fail linting without fixes.

• Hypervisor Abstraction Layer — Multipass supports KVM, QEMU, Hyper-V, and VirtualBox via AbstractPlatform interface; understanding the abstraction pattern is critical for adding new backend support or debugging platform-specific bugs
• Cloud-init Metadata Service — Multipass injects cloud-init userdata/metadata to instances without manual SSH; grasping this pattern is essential for understanding how Multipass automates VM initialization
• gRPC Service Layer — CLI and GUI clients communicate with the daemon via gRPC; .proto files define the RPC contract, and vendored gRPC patches in vcpkg-ports/ are mandatory for builds
• Copy-on-Write (CoW) Storage — Multipass uses CoW snapshots for instance root filesystems to minimize disk overhead; understanding CoW is crucial for optimizing image caching and instance cloning
• QEMU Command-Line Interface (QMP) — Multipass controls QEMU instances via QMP protocol for lifecycle management (suspend/resume/stop); QMP commands are marshaled through src/qemu_sysroot/
• Platform Detection & CMake Cross-Compilation — CMakeLists.txt uses CMAKE_SYSTEM_NAME to conditionally compile platform-specific code; misunderstanding this leads to build failures or runtime platform mismatches
• vcpkg Port Overlays — 3rd-party/vcpkg-ports/ overrides upstream grpc port with Multipass-specific patches; this is non-standard vcpkg usage and requires careful maintenance when upgrading gRPC

• moby/moby — Docker achieves similar lightweight containerization but via containers instead of VMs; Multipass users often compare for resource-constrained scenarios
• hashicorp/vagrant — Vagrant orchestrates VMs with more configuration complexity; Multipass is the minimalist alternative for quick Ubuntu VM provisioning
• lima-vm/lima — CNCF-hosted lightweight VM manager for Linux/macOS with similar architecture (hypervisor abstraction, cloud-init); direct competitor using different approach
• canonical/cloud-init — Multipass integrates cloud-init for instance metadata/initialization; cloud-init is the backend powering user-data injection and networking configuration
• canonical/ubuntu-image — Multipass uses ubuntu-image to fetch and cache Ubuntu cloud images; understanding image preparation is essential for debugging instance boot failures

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for vcpkg-ports patches and portfile configurations

The 3rd-party/vcpkg-ports directory contains multiple complex custom ports (grpc, libssh, premock) with numerous patches and CMake configurations, but there's no visible test workflow validating that these patches apply cleanly, don't conflict, and maintain compatibility across platforms. This is critical since build failures in these dependencies would block all platform-specific builds (Linux, macOS, Windows).

• [ ] Create .github/workflows/vcpkg-ports-validation.yml to test patch application against upstream versions
• [ ] Add validation script in 3rd-party/vcpkg-ports/ to verify portfile.cmake syntax and vcpkg.json validity
• [ ] Test that grpc patches (00001-fix-uwp.patch through 00017-add-src-upb.patch) apply without conflicts
• [ ] Validate libssh multipass-patches don't conflict with base patches
• [ ] Include cross-platform checks since grpc has platform-specific patches (e.g., link-gdi32-on-windows)

Implement automated dependency freshness checks for sphinx documentation dependencies

The docs/requirements.txt or equivalent (referenced in Dependencies/Config) pins many sphinx extensions (myst-parser~=4.0, sphinx-design, sphinx-roles, etc.) but there's no visible workflow like .github/workflows/monitor-usns.yml equivalents for documentation dependencies. With the comment 'v5.0.0 causes version conflicts', this needs systematic monitoring to catch security updates and compatibility issues before they break the doc build.

• [ ] Create .github/workflows/docs-deps-check.yml to run dependabot or pip-audit on docs dependencies weekly
• [ ] Add automated PR generation when sphinx-related CVEs are detected in monitoring
• [ ] Document the myst-parser~=4.0 constraint and v5.0.0 incompatibility in docs/requirements.txt comments
• [ ] Add step to existing lint.yml or automatic-doc-checks.yml to validate docs build with pinned versions

Add GitHub Actions workflow for validating clang-format and clang-tidy configurations across platform builds

The repo has .clang-format and .clang-tidy files at root and in 3rd-party/, but there's no dedicated lint workflow visible that validates these configs are consistent and actually enforced during Linux, macOS, and Windows builds. The existing lint.yml workflow likely doesn't validate C++ formatting comprehensively across the multipass codebase (src/ appears to be the main source but isn't in the file listing provided).

• [ ] Create or enhance .github/workflows/lint.yml to include clang-format validation on all src/ files
• [ ] Add clang-tidy checks that run during the lint workflow before platform-specific builds (linux.yml, macos.yml, windows.yml)
• [ ] Verify .clang-format and 3rd-party/.clang-format are consistent in formatting rules; document any intentional differences
• [ ] Add check-clang-format step that fails PR if any C++ files don't match formatting (integrate with PR template)

• Add Python integration tests for the macOS Hyper-V backend in tests/slow/mac/ (currently skipped or minimal coverage); mirror existing KVM test patterns from tests/slow/linux/
• Document the gRPC service definition workflow: create docs/development/grpc-workflow.md explaining .proto file location, regeneration steps, and C++ stub usage since 3rd-party/vcpkg-ports/grpc/ patches are non-obvious
• Implement missing --json flag for multipass list and multipass info commands in src/client/cli/ to match feature parity with Terraform provider; add YAML serialization tests in tests/

Multipass demonstrates a reasonable security posture with GitHub security advisory reporting configured and active CI/CD pipelines. However, several opportunities for improvement exist: dependency management lacks explicit pinning and automated scanning, third-party patches need better documentation, and C++ static analysis security checks should be verified. The main risks are inherited from outdated dependencies and unverified third-party sphinx extensions. No hardcoded secrets, SQL injection, XSS, or infrastructure misconfigurations were detected in the visible files. Recommend implementing automated dependency vulnerability scanning and more rigorous version pinning across all requirements.

• Medium · Outdated Sphinx Documentation Dependencies — Dependencies/Package file (Sphinx documentation requirements). The dependencies file pins myst-parser to ~=4.0 with a comment stating 'v5.0.0 causes version conflicts'. This suggests known compatibility issues that may indicate security concerns with the newer version. Additionally, multiple sphinx extensions are pinned to older versions (>=0.1.0) which may contain unpatched vulnerabilities. Fix: 1. Resolve the version conflicts with myst-parser v5.0.0 and upgrade to the latest stable version. 2. Run 'pip-audit' or 'safety' to identify CVEs in pinned dependencies. 3. Update sphinx extensions to their latest secure versions and test thoroughly.
• Medium · Unspecified Minimum Version for Core Dependencies — Dependencies/Package file. Several dependencies lack specific minimum versions (e.g., 'packaging', 'rst2html', 'vale'). This allows pip to install potentially outdated and vulnerable versions if not explicitly constrained elsewhere. Fix: Specify minimum versions for all dependencies: 'packaging>=20.0', 'rst2html>=1.0', 'vale>=2.0' (adjust versions based on actual requirements). Use pip-compile or Poetry to lock all transitive dependencies.
• Medium · Missing Dependency Verification in CI/CD — .github/workflows/ directory. The GitHub workflows (.github/workflows/) do not explicitly show dependency scanning, SBOM generation, or vulnerability scanning steps. The repository uses external dependencies but lacks visible automated security scanning. Fix: 1. Add 'pip-audit' or 'safety' scanning to lint.yml workflow. 2. Implement Dependabot for automated dependency updates. 3. Use GitHub's native 'Dependency scanning' and 'Secret scanning' features. 4. Consider adding SBOM generation in build pipelines.
• Low · No Explicit Security Configuration in .clang-tidy — .clang-tidy and 3rd-party/.clang-tidy. The .clang-tidy files exist but their content is not visible. These should include security-focused checks. The C++ codebase (implied by clang configuration) may lack static analysis security checks. Fix: Ensure .clang-tidy includes security checks: 'cert-', 'clang-analyzer-security.', 'readability-*'. Verify clang-tidy is run in CI pipeline (monitor-usns.yml exists but purpose is unclear).
• Low · Third-Party Patches Without Audit Trail — 3rd-party/vcpkg-ports/ directory. Multiple third-party patches exist in 3rd-party/vcpkg-ports/ (grpc, libssh, premock). While patches are named logically, there's no visible security review process or documentation of why each patch was applied. Fix: 1. Document each patch with rationale and security implications in README files. 2. Establish a process for reviewing and vetting patches before application. 3. Track patch versions against upstream security advisories.
• Low · Sphinx Documentation Extensions May Have Unknown Risks — Dependencies/Package file - sphinx extensions. Multiple sphinx extensions (sphinx-filtered-toctree, sphinx-roles, sphinx-terminal, sphinx-ubuntu-images, sphinx-youtube-links) are third-party packages with minimal version constraints. These execute during documentation builds and could be vectors for supply chain attacks. Fix: 1. Review each sphinx extension's source code and maintainer reputation. 2. Pin to specific versions rather than ranges (>=0.1.0). 3. Run hash verification for downloaded packages. 4. Consider using a private package mirror for production builds.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.