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/dotless-de/vagrant-vbguest 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.

WAIT — Stale — last commit 2y ago

• 13 active contributors
• MIT licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 86% of recent commits
• ⚠ No CI workflows detected

_{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 dotless-de/vagrant-vbguest repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dotless-de/vagrant-vbguest.

What it runs against: a local clone of dotless-de/vagrant-vbguest — 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 dotless-de/vagrant-vbguest | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 904 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dotless-de/vagrant-vbguest. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dotless-de/vagrant-vbguest.git
#   cd vagrant-vbguest
#
# 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 dotless-de/vagrant-vbguest and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "lib/vagrant-vbguest.rb" \\
  && ok "lib/vagrant-vbguest.rb" \\
  || miss "missing critical file: lib/vagrant-vbguest.rb"
test -f "lib/vagrant-vbguest/installer.rb" \\
  && ok "lib/vagrant-vbguest/installer.rb" \\
  || miss "missing critical file: lib/vagrant-vbguest/installer.rb"
test -f "lib/vagrant-vbguest/installers/base.rb" \\
  && ok "lib/vagrant-vbguest/installers/base.rb" \\
  || miss "missing critical file: lib/vagrant-vbguest/installers/base.rb"
test -f "lib/vagrant-vbguest/middleware.rb" \\
  && ok "lib/vagrant-vbguest/middleware.rb" \\
  || miss "missing critical file: lib/vagrant-vbguest/middleware.rb"
test -f "lib/vagrant-vbguest/config.rb" \\
  && ok "lib/vagrant-vbguest/config.rb" \\
  || miss "missing critical file: lib/vagrant-vbguest/config.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 904 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~874d)"
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/dotless-de/vagrant-vbguest"
  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).

vagrant-vbguest is a Vagrant plugin that automatically detects and installs matching VirtualBox Guest Additions inside guest VMs, eliminating manual version mismatches. It handles OS-specific installation (Linux distros, Windows) by downloading the correct VBoxGuestAdditions.iso and executing platform-specific installers, ensuring shared folders and video acceleration work out of the box. Single-package Vagrant plugin structure: lib/vagrant-vbguest/ contains the core with modular installers (lib/vagrant-vbguest/installers/) for each OS (ubuntu.rb, centos.rb, windows.rb, etc.), helpers for OS detection (lib/vagrant-vbguest/helpers/), middleware hook integration (middleware.rb), and configuration (config.rb). Locales/ adds i18n strings. testdrive/ provides a Vagrant test environment.

Vagrant users (developers, DevOps engineers, infrastructure-as-code practitioners) who provision VirtualBox VMs and need Guest Additions kept in sync with their host VirtualBox version without manual intervention or post-provision scripting.

Archived as of 2023-12-17 and no longer receiving updates. The project is stable and production-tested (evident from gem badge and Code Climate integration), but is effectively in maintenance-only mode. Not recommended for new projects; existing deployments continue to work.

HIGH RISK: Project is archived with no future maintenance. Single maintainer (dotless-de org). Dependency chain relies on Vagrant plugin API stability; breaking Vagrant versions will break this plugin with no fix forthcoming. ISO download URLs (virtualbox.org) may change. Consider forking if you depend on this for critical infrastructure.

Nothing. Project is archived. Last activity appears to be dependency updates via Dependabot (visible in .github/dependabot.yml), but no new feature work or bug fixes are being merged.

git clone https://github.com/dotless-de/vagrant-vbguest.git
cd vagrant-vbguest
bundle install
bundle exec rake test  # Run tests
bundle exec vagrant up  # Try testdrive/Vagrantfile

Daily commands: As a plugin: vagrant plugin install vagrant-vbguest then vagrant up (auto-runs). For development: cd testdrive && ./bin/vagrant up uses local plugin. Tests: bundle exec rake test.

• lib/vagrant-vbguest.rb — Plugin entry point—registers the plugin with Vagrant and initializes core components that every contributor must understand
• lib/vagrant-vbguest/installer.rb — Abstract installer interface that all OS-specific installers inherit from; essential to understand before adding support for new guest OS types
• lib/vagrant-vbguest/installers/base.rb — Base installer class defining the installation workflow and command execution pattern used across all OS implementations
• lib/vagrant-vbguest/middleware.rb — Vagrant middleware hook that triggers Guest Additions installation; controls when and how the plugin integrates with Vagrant's lifecycle
• lib/vagrant-vbguest/config.rb — Configuration schema for user settings; critical for understanding what options are exposed to Vagrantfile users
• lib/vagrant-vbguest/download.rb — Handles downloading Guest Additions ISO from host system; core dependency resolution logic
• lib/vagrant-vbguest/hosts/virtualbox.rb — VirtualBox host integration layer that detects and retrieves Guest Additions from the VirtualBox installation

• Middleware (Vagrant middleware hooks, Ruby) — Intercepts Vagrant VM lifecycle events and orchestrates the entire installation workflow
  • Failure mode: Silent failure if installation fails; logs are available but user may not notice Guest Additions not installed
• Installer Registry (Ruby class factory pattern) — Detects guest OS and selects the correct OS-specific installer implementation
  • Failure mode: Unsupported OS falls back to base Linux installer or fails with unknown OS error
• Base Installer (Ruby, SSH command execution) — Defines the installation workflow: upload ISO, mount, execute, cleanup, optional reboot
  • Failure mode: Installation incomplete if any step fails; VM left in partially-installed state requiring manual recovery
• OS Release Helper (SSH file reading, /etc/os-release standard) — Detects guest OS type and version by reading /etc/os-release or platform-specific files
  • Failure mode: Incorrect OS detection leads to wrong installer selection; custom/minimal Linux distros may not be detected
• VirtualBox Host Detection (VirtualBox CLI, filesystem detection) — Locates host VirtualBox installation and provides Guest Additions ISO to install on guest
  • Failure mode: If VirtualBox not found, plugin cannot locate Guest

Add Support for a New Linux Distribution

1. Create a new installer class in lib/vagrant-vbguest/installers/ that inherits from Linux or Base (lib/vagrant-vbguest/installers/mydistro.rb)
2. Implement install method with distribution-specific package manager commands and dependencies (lib/vagrant-vbguest/installers/mydistro.rb)
3. Register the installer in the Installer class by adding it to the guest_additions_versions or installer_map (lib/vagrant-vbguest/installer.rb)
4. Add OS detection logic in os_release.rb helper if needed to match your distribution's release file (lib/vagrant-vbguest/helpers/os_release.rb)
5. Add locale strings for your distribution in locales/en_mydistro.yml (locales/en_mydistro.yml)

Add a New User Configuration Option

1. Define the new config attribute in the Config class with validation (lib/vagrant-vbguest/config.rb)
2. Update the middleware or installer to check and use the new config option (lib/vagrant-vbguest/middleware.rb)
3. Add locale strings for info/warning messages related to the new option (locales/en.yml)

Customize the Download Strategy for Guest Additions

1. Extend or modify the Download class to handle alternative ISO sources (lib/vagrant-vbguest/download.rb)
2. Update the host virtualbox.rb to override the default Guest Additions location if needed (lib/vagrant-vbguest/hosts/virtualbox.rb)
3. Add config options to allow users to specify custom download URLs (lib/vagrant-vbguest/config.rb)

• Ruby — Vagrant itself is Ruby-based; plugin must use the same language to hook into Vagrant's middleware and configuration systems
• VirtualBox CLI — Primary interface to detect host VirtualBox installation and retrieve Guest Additions ISO; no other reliable cross-platform method
• Platform-specific package managers (apt, yum, pacman, etc.) — Each guest OS has native dependency management; using native tools ensures compatibility and proper system integration

• Plugin-based architecture for different guest OSes rather than universal installer

  • Why: Each OS has different installation requirements, paths, and dependencies; universal approach would be unreliable
  • Consequence: Requires adding new installer classes for each new guest OS type; makes plugin more maintainable but slower to add support

• Download Guest Additions ISO from VirtualBox host detection rather than pre-packaged

  • Why: Allows plugin to stay synchronized with host VirtualBox version without manual updates
  • Consequence: Adds runtime download overhead and dependency on VirtualBox installation detection; requires active network access

• Integrate via Vagrant middleware hooks rather than custom provisioner

  • Why: Automatic and transparent integration into VM lifecycle; no manual user configuration needed
  • Consequence: Limited control for users who want conditional or staged installation; hidden behavior can surprise users

• Does not support non-VirtualBox hypervisors (Hyper-V, VMware, KVM, etc.)
• Does not handle custom or proprietary guest operating systems not in the installer registry
• Does not support downgrading Guest Additions to older versions
• Project is archived as of 2023-12-17 and will not receive further updates or support

Archive status: Plugin no longer updated; Vagrant version 2.3+ may break compatibility. URL templating: iso_path with %{version} requires manual VirtualBox version detection; test with multiple VBox versions. ISO mount points: Assumes /mnt or /tmp are writable; fails silently on locked-down guest systems. Relative paths: Relative iso_path is relative to pwd not Vagrantfile; use File.expand_path(FILE) trick documented in README. Reboot handling: rebootable.rb checks for reboot capability; some guest OSes (lightweight Linux) may lack reboot command. Windows installer: windows.rb may fail if guest lacks Administrator context or if VirtualBox Tools service blocks uninstall.

• Vagrant Middleware Hooks — vagrant-vbguest integrates via middleware.rb into Vagrant's action chain; understanding trigger points (after boot, before provisioning) is essential to knowing when Guest Additions get installed
• Linux /etc/os-release Standard — helpers/os_release.rb parses this file to detect distro name/version; knowing this standard is key to understanding why different Linux installers are selected
• VirtualBox Guest Additions ISO Format — The plugin downloads and mounts VBoxGuestAdditions.iso which contains OS-specific installer scripts (VBoxLinuxAdditions.run, certificate.sh, etc.); understanding the ISO structure explains why installers must parse and execute specific scripts
• Ruby Gem Plugin System (Vagrant) — vagrant-vbguest is packaged as a Ruby gem that Vagrant dynamically loads; the VERSION file and gemspec pattern matter for versioning and distribution
• Shell Command Injection via Guest Execution — The plugin runs arbitrary shell scripts on the guest (installers/*.rb call system commands like apt-get, yum, etc.). Understanding how download.rb and machine.rb escape/sanitize version strings prevents command injection
• ISO 9660 Filesystem Mounting — The plugin mounts VBoxGuestAdditions.iso on the guest using mount(8); understanding how installers handle mount points (default /mnt) and handle mount failures is crucial for debugging installation failures on exotic guest OSes
• URL Template Substitution Pattern — iso_path config accepts %{version} placeholder (e.g., 'http://mirror.example.com/%{version}/VBoxGuestAdditions.iso'); understanding how download.rb interpolates this is key to configuring custom ISO mirrors

• vagrant/vagrant — The core Vagrant project; vagrant-vbguest is a plugin that hooks into Vagrant's middleware and provisioning lifecycle
• chef-boneyard/vagrant-omnibus — Similar Vagrant plugin pattern: auto-installs Chef on guests. Shows alternative approaches to guest-side provisioning
• hashicorp/vagrant-vmware-desktop — Official VMware provider plugin; demonstrates Vagrant's provider abstraction that vbguest hooks into
• void-linux/xbps-src-vagrant — Uses vagrant-vbguest in its Vagrantfile; real-world consumer showing the plugin in production use

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 suite for installer classes

The repo has multiple OS-specific installer classes (archlinux.rb, centos.rb, debian.rb, ubuntu.rb, windows.rb, etc.) in lib/vagrant-vbguest/installers/ but no visible test directory. This is critical for a plugin that must work reliably across diverse Linux distributions and Windows. A proper test suite would catch OS-specific installation failures early.

• [ ] Create test/ directory with test_helper.rb setup
• [ ] Add unit tests for lib/vagrant-vbguest/installers/base.rb covering core installation logic
• [ ] Add tests for OS-specific installers (ubuntu.rb, centos.rb, windows.rb) verifying correct package managers and commands
• [ ] Add tests for lib/vagrant-vbguest/download.rb to verify file download and integrity
• [ ] Integrate tests into Rakefile and configure CI workflow to run them

Add GitHub Actions CI workflow for plugin validation

The repo has a .github/dependabot.yml but no visible test automation workflow. This plugin must work across multiple Vagrant versions and OS targets. A CI workflow would catch regressions when dependencies update or code changes are made, especially critical given the project is archived but still in use.

• [ ] Create .github/workflows/test.yml with matrix testing for multiple Ruby versions (2.6+)
• [ ] Add Bundler dependency installation and RSpec/Minitest execution steps
• [ ] Add a linting job using RuboCop against lib/ directory
• [ ] Configure workflow to run on pull requests and on dependabot updates
• [ ] Add workflow badge to README.md

Document the upgrade path and breaking changes in CHANGELOG.md and migration guide

The project is archived as of 2023-12-17 per the README, but there's no explicit migration guide for users to understand which versions are stable, what breaking changes exist between versions, or alternatives. The CHANGELOG.md exists but lacks detailed version histories. Users need clarity on what version to use.

• [ ] Review VERSION file and git history to backfill CHANGELOG.md with detailed entries for last 5-10 releases with breaking changes clearly marked
• [ ] Create MIGRATION.md documenting known issues with modern Vagrant/VirtualBox versions and workarounds
• [ ] Add section to README.md under 'Maintenance Status' listing recommended alternatives (e.g., official plugins, maintained forks)
• [ ] Document minimum supported Vagrant and VirtualBox versions in README.md requirements section

• Add test coverage for lib/vagrant-vbguest/download.rb (URL templating edge cases, 404 handling). Current test files are sparse; downloading with malformed version strings or unreachable servers is untested.
• Document the installer selection logic flow in README. The cascade from os_release.rb → machine.rb → installer selection is non-obvious; new contributors need a diagram or flowchart.
• Extend lib/vagrant-vbguest/helpers/vm_compatible.rb to validate guest VirtualBox version matches host before attempting install. Currently it warns but doesn't prevent mismatches, leading to cryptic installer failures.

The vagrant-vbguest project has a critical issue: it was archived in December 2023 and will receive no further security updates. This is the primary security concern. Secondary concerns include an overly restrictive version support policy, inability to audit current dependencies due to missing dependency file contents, and minor concerns about GPG key distribution practices. The codebase itself appears to follow reasonable security patterns based on the file structure (no obvious hardcoded secrets, Docker exposure, or injection vulnerabilities detected), but the lack of active maintenance is a significant risk factor for production use.

• High · Project Archived and Unsupported — README.md, Project Status. The project was archived on 2023-12-17 and will no longer receive security updates, bug fixes, or maintenance from the original author. This means any newly discovered vulnerabilities will not be patched. Fix: Users should consider migrating to actively maintained alternatives or fork the project if continued use is necessary. If forking, establish a security maintenance process.
• Medium · Overly Permissive Security Policy — SECURITY.md. The SECURITY.md specifies that only the latest version receives security updates. This is a very restrictive policy that forces all users to immediately upgrade, which may not be practical in production environments with compatibility constraints. Fix: Consider supporting at least the last 2-3 minor versions with security patches to allow users reasonable time for upgrades and testing.
• Medium · Dependency Information Not Provided — Gemfile, vagrant-vbguest.gemspec. The Gemfile and gemspec files are present in the file structure, but their contents were not provided for analysis. This prevents assessment of whether the project uses vulnerable or outdated Ruby gem dependencies. Fix: Perform a dependency audit using 'bundler-audit' or 'bundle audit' to identify known vulnerabilities in gem dependencies. Consider enabling Dependabot for automated dependency scanning.
• Low · GPG Key Distribution Over HTTPS Only — SECURITY.md. The SECURITY.md directs users to download the GPG key from Keybase over HTTPS. While better than HTTP, there's no mention of verifying the key fingerprint through an out-of-band channel or using a keyserver. Fix: Document best practices for key verification. Consider publishing the key on multiple public keyservers (keys.openpgp.org, pgp.mit.edu) to reduce reliance on a single distribution point.
• Low · Test Drive Environment Security — testdrive/. The testdrive directory contains sample/test vagrant configurations and a nested plugin (vagrant-vbguest-unikorn) that could potentially be exploited if committed with sensitive data or misconfigured settings. Fix: Ensure testdrive configurations do not contain credentials, API keys, or sensitive settings. Add testdrive to .gitignore if it's meant for local development only, or sanitize all example configurations.

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.