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/mitchellh/vagrant-aws 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 all four use cases

• 26+ active contributors
• Distributed ownership (top contributor 38% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 5y ago

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

What it runs against: a local clone of mitchellh/vagrant-aws — 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 mitchellh/vagrant-aws | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1830 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mitchellh/vagrant-aws(\\.git)?\\b" \\
  && ok "origin remote is mitchellh/vagrant-aws" \\
  || miss "origin remote is not mitchellh/vagrant-aws (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/vagrant-aws/plugin.rb" \\
  && ok "lib/vagrant-aws/plugin.rb" \\
  || miss "missing critical file: lib/vagrant-aws/plugin.rb"
test -f "lib/vagrant-aws/provider.rb" \\
  && ok "lib/vagrant-aws/provider.rb" \\
  || miss "missing critical file: lib/vagrant-aws/provider.rb"
test -f "lib/vagrant-aws/action.rb" \\
  && ok "lib/vagrant-aws/action.rb" \\
  || miss "missing critical file: lib/vagrant-aws/action.rb"
test -f "lib/vagrant-aws/config.rb" \\
  && ok "lib/vagrant-aws/config.rb" \\
  || miss "missing critical file: lib/vagrant-aws/config.rb"
test -f "lib/vagrant-aws/action/connect_aws.rb" \\
  && ok "lib/vagrant-aws/action/connect_aws.rb" \\
  || miss "missing critical file: lib/vagrant-aws/action/connect_aws.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 1830 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1800d)"
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/mitchellh/vagrant-aws"
  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-aws is a Vagrant provider plugin that enables infrastructure-as-code management of AWS EC2 and VPC instances using Vagrant's familiar CLI and Vagrantfile syntax. It bridges Vagrant's provisioning and lifecycle management capabilities directly to AWS, letting developers boot, SSH into, provision, and package EC2 instances through vagrant up --provider=aws without leaving the Vagrant workflow. Standard Ruby gem structure: lib/vagrant-aws/ contains the core plugin with action chain middleware in lib/vagrant-aws/action/ (e.g., connect_aws.rb, run_instance.rb, read_ssh_info.rb), config.rb for Vagrantfile DSL, provider.rb as the Vagrant provider interface, and lib/vagrant-aws/util/ for ELB and timer helpers. A dummy.box and example_box/ demonstrate usage patterns.

DevOps engineers and developers who already use Vagrant for local development but need to scale to cloud infrastructure; teams that want to manage EC2 instances with the same Vagrantfile and provisioning scripts they use for VirtualBox/VMware, avoiding context-switching between tools.

Actively maintained but shows signs of age: the README targets Vagrant 1.2+ (released 2012), has minimal test coverage (only spec/vagrant-aws/config_spec.rb visible), CI via .travis.yml suggests older testing practices, and the repository lacks recent commit metadata in the provided data. Likely production-ready for basic use cases but not under active feature development.

Single-maintainer risk (mitchellh, though likely has collaborators): the plugin depends on Vagrant core APIs that may break across major versions, AWS SDK compatibility requires active maintenance, and sparse test coverage means regressions could slip through. No indication of automated dependency updates or security patch discipline visible.

Unable to determine from the file metadata provided (no commit hashes, timestamps, or PR list visible). The presence of CHANGELOG.md suggests version tracking, but recency is unknown.

git clone https://github.com/mitchellh/vagrant-aws.git
cd vagrant-aws
bundle install
bundle exec rake

Daily commands: This is a Vagrant plugin, not an app. Install via vagrant plugin install vagrant-aws, then create a Vagrantfile with config.vm.provider :aws do |aws| ... end and run vagrant up --provider=aws. Development: bundle exec rake runs tests (see Rakefile).

• lib/vagrant-aws/plugin.rb — Entry point that registers the AWS provider with Vagrant; every contributor must understand how this plugin integrates with Vagrant's plugin system
• lib/vagrant-aws/provider.rb — Core provider implementation that defines the machine lifecycle (up, down, ssh, etc.); essential for understanding the provider's public interface
• lib/vagrant-aws/action.rb — Action middleware builder that orchestrates all AWS operations; foundation for understanding how commands chain together
• lib/vagrant-aws/config.rb — Configuration schema and validation; defines all AWS-specific settings users can specify in Vagrantfile
• lib/vagrant-aws/action/connect_aws.rb — Establishes AWS SDK connection; critical dependency for all AWS API calls in the action pipeline
• lib/vagrant-aws/action/run_instance.rb — Launches EC2 instances with configuration; one of the most complex actions implementing the core 'vagrant up' feature
• lib/vagrant-aws.rb — Gem entry point and version definition; required for understanding plugin initialization

Add a new AWS action (e.g., reboot instance)

1. Create a new action file in lib/vagrant-aws/action/ that inherits from the action base class and implements the #call method (lib/vagrant-aws/action/reboot_instance.rb)
2. Register the action in the appropriate command chain in lib/vagrant-aws/action.rb under the action builder method (lib/vagrant-aws/action.rb)
3. Add error handling using error classes from lib/vagrant-aws/errors.rb if needed (lib/vagrant-aws/errors.rb)
4. Add localization strings for user messages in locales/en.yml (locales/en.yml)

Add a new configuration option

1. Add the attribute definition to the Config class with proper type and default in lib/vagrant-aws/config.rb (lib/vagrant-aws/config.rb)
2. Use the configuration value in the action that needs it (typically in lib/vagrant-aws/action/run_instance.rb for instance launch options) (lib/vagrant-aws/action/run_instance.rb)
3. Document the option in README.md with usage example (README.md)

Add ELB integration to an existing action

1. Use the ELB utility methods from lib/vagrant-aws/util/elb.rb in your action (lib/vagrant-aws/util/elb.rb)
2. Call register_instance or deregister_instance as needed in your action's #call method (lib/vagrant-aws/action/elb_register_instance.rb)
3. Add to the appropriate action chain in lib/vagrant-aws/action.rb (lib/vagrant-aws/action.rb)

Add a new provider state check

1. Create a predicate action in lib/vagrant-aws/action/ (e.g., is_stopped.rb) that checks instance state (lib/vagrant-aws/action/is_created.rb)
2. Use it in action chains to conditionally execute downstream actions based on state (lib/vagrant-aws/action.rb)
3. Pair with message actions (e.g., message_already_created.rb) to inform users (lib/vagrant-aws/action/message_already_created.rb)

• Ruby & Vagrant Plugin API — Vagrant is a Ruby framework; plugins must be Ruby and integrate via Vagrant's well-defined provider interface
• aws-sdk (Fog) — Industry-standard Ruby library for AWS API interactions; provides abstraction over raw HTTP/JSON
• Middleware/Action pattern — Allows composable, chainable operations that can be conditionally skipped or reordered without tight coupling
• RSpec for testing — Ruby community standard; integrates with Vagrant's test ecosystem

• Action-based architecture instead of direct method calls

  • Why: Enables plugins and extensions to wrap/modify behavior; supports conditional execution; allows middleware-style filtering
  • Consequence: Added complexity with more files, but gains flexibility for advanced use cases and plugin composition

• Polling-based state waits instead of event streams

  • Why: AWS API does not provide real-time events; polling is simpler and more compatible
  • Consequence: Slight latency and API call overhead, but reliable and doesn't require external event infrastructure

• Minimal synced folder support (rsync only)

  • Why: EC2 instances lack built-in shared folders like VirtualBox; rsync is portable and doesn't require agent software
  • Consequence: Users lose convenience of two-way syncing; must use rsync or provision file distribution themselves

• Region-specific configurations at machine level

  • Why: Allows single Vagrantfile to manage machines across multiple AWS regions without complex env vars
  • Consequence: Config schema is more complex, but enables multi-region deployments

• Manage VPC networking configuration (can launch into VPCs but does not create them)
• Handle IAM role or policy creation (users must pre-create and configure)
• Provide real-time log streaming (relies on SSH for access)
• Manage RDS databases or other AWS services beyond EC2/VPC
• Support Windows instances (focused on Linux provisioning via SSH)
• Implement full synced folder feature parity with VirtualBox

AWS credentials required: must set aws.access_key_id, aws.secret_access_key via config, environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), or ~/.aws/ config. Security group must allow SSH inbound (port 22) or vagrant ssh will hang. Region must be specified (default likely us-east-1); VPC/subnet configuration is non-obvious—see example_box/Vagrantfile. The dummy.box has no AMI defaults, forcing manual ami specification. Synced folders use only rsync (no native VirtualBox shared folders equivalent).

• Vagrant Provider Plugin Architecture — This entire codebase is built on Vagrant's provider SPI (Service Provider Interface); understanding how providers register actions, manage machine state, and integrate provisioners is essential to modifying vagrant-aws
• Action Middleware / Chain Pattern — vagrant-aws orchestrates EC2 lifecycle (connect → launch → wait → read_state) via composable action middleware; modifying or adding steps requires understanding how lib/vagrant-aws/action.rb chains actions
• AWS EC2 Instance Lifecycle & State Machine — The plugin manages instance states (pending → running → stopping → stopped → terminating → terminated); lib/vagrant-aws/action/wait_for_state.rb and read_state.rb depend on understanding these transitions for correct polling and error handling
• SSH Bastion / Jumphost Patterns — read_ssh_info.rb determines how Vagrant reaches instances (public IP, Elastic IP, or VPC private IP); understanding network topology is critical for SSH provisioning to work across VPC/security group boundaries
• AWS Elastic Load Balancer (ELB) Registration — lib/vagrant-aws/util/elb.rb and elb_register_instance.rb integrate instances into load balancers; understanding ELB health checks and instance registration is needed for production-like multi-instance setups
• Ruby Gem Plugin System & Rubygems — vagrant-aws is distributed as a RubyGem (vagrant-aws.gemspec); understanding how Vagrant discovers and loads plugins via gem dependencies and load paths is necessary for debugging version conflicts
• Configuration DSL Evaluation — lib/vagrant-aws/config.rb uses Vagrant's block-based config syntax (e.g., aws.ami = '...'); understanding how the DSL validates and merges multi-level configs is key to extending the Vagrantfile interface

• hashicorp/vagrant — Core dependency and provider interface definition; vagrant-aws extends Vagrant's provider system
• mitchellh/vagrant-digitalocean — Sibling provider plugin by same author for DigitalOcean; demonstrates alternate cloud provider pattern using same Vagrant plugin architecture
• hashicorp/terraform — Alternative IaC tool for AWS that some teams use instead of Vagrant; Terraform can manage the same EC2 infrastructure with different DSL and state management
• aws/aws-sdk-ruby — Direct dependency; vagrant-aws wraps this SDK to call EC2 API
• mitchellh/vagrant-vmware-desktop — Another official provider plugin showing how Vagrant provider architecture extends to other hypervisors

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 unit tests for action classes in lib/vagrant-aws/action/

The repo has spec/vagrant-aws/config_spec.rb but no tests for the critical action classes (run_instance.rb, terminate_instance.rb, stop_instance.rb, start_instance.rb, etc.). These actions directly manage EC2 lifecycle and are high-risk for bugs. Adding tests would catch regressions in AWS API interactions and state transitions.

• [ ] Create spec/vagrant-aws/action/ directory structure
• [ ] Add spec/vagrant-aws/action/run_instance_spec.rb with mocked AWS SDK calls
• [ ] Add spec/vagrant-aws/action/terminate_instance_spec.rb and stop_instance_spec.rb
• [ ] Add spec/vagrant-aws/action/elb_register_instance_spec.rb and elb_deregister_instance_spec.rb
• [ ] Add integration test helpers in spec/spec_helper.rb for common mocking patterns
• [ ] Ensure .travis.yml runs the new test suite

Add missing documentation for ELB (Elastic Load Balancer) configuration in README.md

The codebase contains lib/vagrant-aws/action/elb_register_instance.rb, lib/vagrant-aws/action/elb_deregister_instance.rb, and lib/vagrant-aws/util/elb.rb, but the README.md snippet cuts off mid-sentence and contains no mention of ELB feature setup. Contributors and users need documented examples of how to configure ELB integration.

• [ ] Complete the truncated 'Package running ins' sentence in README.md
• [ ] Add new 'ELB Configuration' section with example Vagrantfile showing elb_load_balancers config
• [ ] Document how to associate/disassociate instances from load balancers
• [ ] Add code examples referencing the actual config options that map to lib/vagrant-aws/config.rb
• [ ] Document any prerequisites (IAM permissions, existing load balancer setup)

Add unit tests for lib/vagrant-aws/util/elb.rb and lib/vagrant-aws/util/timer.rb

These utility modules handle critical functionality (load balancer operations and timeout management) but lack test coverage. The timer.rb is especially important as it manages instance state polling timeouts, which directly affects user experience and AWS billing.

• [ ] Create spec/vagrant-aws/util/elb_spec.rb testing ELB registration/deregistration logic
• [ ] Add test cases for error handling when ELB doesn't exist or instance not found
• [ ] Create spec/vagrant-aws/util/timer_spec.rb testing timeout calculations and callbacks
• [ ] Add edge case tests (timeouts, concurrent calls, state changes during waits)
• [ ] Reference these tests in .travis.yml if not already running spec/ directory

• Add comprehensive unit tests for lib/vagrant-aws/action/wait_for_state.rb and lib/vagrant-aws/action/timed_provision.rb—currently no visible spec files for these core timing operations, risking timeout bugs.
• Document VPC/subnet configuration in the README with a concrete Vagrantfile example (e.g., aws.subnet_id, aws.security_groups)—currently only quick-start example, no VPC guidance despite VPC being in the project title.
• Implement and test lib/vagrant-aws/action/elb_deregister_instance.rb and elb_register_instance.rb flow end-to-end—files exist but no spec coverage visible; unclear if ELB integration fully works.

This Vagrant AWS provider plugin has significant security concerns that cannot be fully assessed without access to the actual implementation details. The primary risks stem from AWS credential handling and SSH key management - both critical areas where misconfiguration could lead to credential exposure. Key gaps include: (1) No visibility into dependency versions and potential vulnerabilities, (2) Unreviewed credential handling implementation, (3) Incomplete security documentation, (4) No security advisory procedures or policy. While the plugin architecture appears sound, the security posture cannot be confirmed without reviewing the full source code, particularly credential handling, logging mechanisms, and SSH key management. Immediate recommendations: conduct a full code security review focusing on credentials/keys, implement automated dependency scanning, and add comprehensive security documentation.

• High · Missing Dependency Security Checks — Gemfile. The Gemfile content was not provided for analysis. Without visibility into the Ruby gem dependencies, it's impossible to verify if known vulnerable versions of gems are being used. This is critical for a plugin that interacts with AWS APIs and handles infrastructure operations. Fix: Ensure all dependencies are pinned to known-secure versions. Run 'bundle audit' regularly to check for known vulnerabilities in dependencies. Implement automated dependency scanning in CI/CD pipeline.
• High · AWS Credentials Handling Not Visible — lib/vagrant-aws/config.rb, lib/vagrant-aws/action/connect_aws.rb. The codebase appears to handle AWS credentials through vagrant configuration, but the actual implementation in key files like 'lib/vagrant-aws/action/connect_aws.rb' and 'lib/vagrant-aws/config.rb' was not provided for review. This is a high-risk area where credentials could be exposed, logged, or stored insecurely. Fix: Ensure AWS credentials are never logged, printed in debug output, or stored in plain text. Use AWS IAM roles when possible. Validate that credentials are only passed through secure channels and that error messages don't leak sensitive information.
• Medium · Incomplete README Security Documentation — README.md. The README appears truncated and doesn't provide security best practices or warnings about credential management. Users may unknowingly expose credentials in their Vagrantfiles or environment configurations. Fix: Add a security section to the README covering: proper credential management, IAM role usage, SSH key handling, and warnings about committing Vagrantfiles with embedded credentials to version control.
• Medium · SSH Key Material Management Not Documented — lib/vagrant-aws/action/read_ssh_info.rb. The plugin manages SSH connections to EC2 instances. The SSH key handling and storage mechanisms are not visible in the provided file structure, but this is a critical security area where private keys could be exposed. Fix: Ensure SSH keys are stored with restrictive file permissions (0600), never logged or displayed in output, and securely transmitted. Validate that key material is not embedded in instance metadata or configuration files that might be committed to version control.
• Low · No CHANGELOG Security Advisories — CHANGELOG.md. The CHANGELOG.md file exists but content wasn't provided. There's no evidence of documented security fixes or security advisory procedures for users of this plugin. Fix: Maintain a security advisories section in CHANGELOG. Clearly document any security-related fixes with severity levels and upgrade recommendations.
• Low · No Security Policy Documentation — Repository root. No SECURITY.md or security policy file is visible in the repository root. Users have no clear process for reporting security vulnerabilities. Fix: Create a SECURITY.md file documenting responsible disclosure procedures, contact information for security reports, and expected response timelines.

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.