# hashicorp/vagrant architecture

> Architecture diagram of the GitHub repository hashicorp/vagrant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hashicorp/vagrant
- Repository: https://github.com/hashicorp/vagrant

## Overview

Vagrant is a CLI and framework for building and managing portable development environments. The documented path is to initialize a project, configure an environment, then bring it up; Vagrant can obtain a box and run it on a local virtualized platform, in cloud infrastructure, or in a container. Its runtime is organized around environment configuration and action execution, with providers, guest/host integrations, communicators, provisioners, and synced folders supplying platform-specific behavior. The README establishes the product workflow and capabilities; internal links not visible in the excerpts are left unverified.

Main entry points: [`lib/vagrant/machine.rb`](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/machine.rb) (Machine Lifecycle), [`plugins/provisioners/chef/provisioner/chef_client.rb`](https://github.com/hashicorp/vagrant/blob/main/plugins/provisioners/chef/provisioner/chef_client.rb) (Chef Provisioner), [`lib/vagrant/bundler.rb`](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/bundler.rb) (Plugin Dependencies), [`lib/vagrant/environment.rb`](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/environment.rb) (Environment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Environment"]
  node_cli["Vagrant CLI<br/>[cli.rb]"]
  node_environment["Environment<br/>[environment.rb]"]
  node_configuration["Environment Config<br/>[config.rb]"]
  node_vagrantfile["Vagrantfile Loading<br/>[vagrantfile.rb]"]
end

subgraph group_core["Runtime Core"]
  node_actions["Action Middleware<br/>[primary_runner.rb]"]
  node_machine["Machine Lifecycle<br/>[machine.rb]"]
  node_boxes["Box Management<br/>[box_collection.rb]"]
  node_boxmeta["Box Metadata<br/>[box_metadata.rb]"]
  node_helpers["Shared Helpers<br/>[shared_helpers.rb]"]
  node_safeenv["Safe Environment<br/>[safe_env.rb]"]
  node_version["Version Utilities<br/>[version.rb]"]
end

subgraph group_platform["Machine Platforms"]
  node_provider["VirtualBox Provider<br/>[action.rb]"]
  node_diskmodel["Storage Controllers"]
  node_diskext["Disk Format Rules"]
end

subgraph group_guestops["Guest Operations"]
  node_communicator["SSH Communicator<br/>[communicator.rb]"]
  node_guests["Guest OS Support<br/>[guest.rb]"]
  node_provision["Chef Provisioner<br/>[chef_client.rb]"]
  node_synced["Synced Folders<br/>[synced_folder.rb]"]
  node_chefbase["Chef Provisioner Base<br/>[base.rb]"]
  node_chefconfig["Chef Client Config<br/>[chef_client.rb]"]
end

subgraph group_extensions["Extensions and State"]
  node_pluginmgr["Plugin Manager<br/>[manager.rb]"]
  node_bundler["Plugin Dependencies<br/>[bundler.rb]"]
  node_state[("Plugin State<br/>[state_file.rb]")]
  node_ftp["FTP Push<br/>[push.rb]"]
  node_ftpadapter["FTP Adapter<br/>[adapter.rb]"]
end

node_user(("Environment Developer"))

node_user -->|"runs commands"| node_cli
node_cli -.->|"manages environments"| node_environment
node_environment -.->|"loads configuration"| node_vagrantfile
node_vagrantfile -.->|"provides settings"| node_configuration
node_environment -.->|"runs actions"| node_actions
node_actions -.->|"manages lifecycle"| node_machine
node_machine -.->|"uses boxes"| node_boxes
node_boxes -.->|"reads metadata"| node_boxmeta
node_machine -.->|"runs on platform"| node_provider
node_diskmodel -->|"validates format"| node_diskext
node_machine -.->|"communicates with guest"| node_communicator
node_machine -.->|"uses guest support"| node_guests
node_machine -.->|"runs provisioning"| node_provision
node_machine -.->|"configures folders"| node_synced
node_pluginmgr -->|"reads and updates"| node_state
node_pluginmgr -->|"resolves plugins"| node_bundler
node_bundler -->|"uses helpers"| node_helpers
node_bundler -->|"uses environment"| node_safeenv
node_bundler -->|"checks version"| node_version
node_provision -->|"inherits behavior"| node_chefbase
node_provision -->|"runs guest commands"| node_communicator
node_provision -.->|"uses configuration"| node_chefconfig
node_ftp -->|"uploads files"| node_ftpadapter

click node_cli "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/cli.rb"
click node_environment "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/environment.rb"
click node_configuration "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/config.rb"
click node_vagrantfile "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/vagrantfile.rb"
click node_actions "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/action/primary_runner.rb"
click node_machine "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/machine.rb"
click node_boxes "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/box_collection.rb"
click node_boxmeta "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/box_metadata.rb"
click node_provider "https://github.com/hashicorp/vagrant/blob/main/plugins/providers/virtualbox/action.rb"
click node_diskmodel "https://github.com/hashicorp/vagrant/blob/main/plugins/providers/virtualbox/model/storage_controller_array.rb"
click node_diskext "https://github.com/hashicorp/vagrant/blob/main/plugins/providers/virtualbox/cap/validate_disk_ext.rb"
click node_communicator "https://github.com/hashicorp/vagrant/blob/main/plugins/communicators/ssh/communicator.rb"
click node_guests "https://github.com/hashicorp/vagrant/blob/main/plugins/guests/linux/guest.rb"
click node_provision "https://github.com/hashicorp/vagrant/blob/main/plugins/provisioners/chef/provisioner/chef_client.rb"
click node_synced "https://github.com/hashicorp/vagrant/blob/main/plugins/synced_folders/nfs/synced_folder.rb"
click node_pluginmgr "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/plugin/manager.rb"
click node_bundler "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/bundler.rb"
click node_state "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/plugin/state_file.rb"
click node_helpers "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/shared_helpers.rb"
click node_safeenv "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/util/safe_env.rb"
click node_version "https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/version.rb"
click node_chefbase "https://github.com/hashicorp/vagrant/blob/main/plugins/provisioners/chef/provisioner/base.rb"
click node_chefconfig "https://github.com/hashicorp/vagrant/blob/main/plugins/provisioners/chef/config/chef_client.rb"
click node_ftp "https://github.com/hashicorp/vagrant/blob/main/plugins/pushes/ftp/push.rb"
click node_ftpadapter "https://github.com/hashicorp/vagrant/blob/main/plugins/pushes/ftp/adapter.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_environment,node_configuration,node_vagrantfile toneBlue
class node_actions,node_machine,node_boxes,node_boxmeta,node_helpers,node_safeenv,node_version toneAmber
class node_provider,node_diskmodel,node_diskext toneMint
class node_communicator,node_guests,node_provision,node_synced,node_chefbase,node_chefconfig toneRose
class node_pluginmgr,node_bundler,node_state,node_ftp,node_ftpadapter,node_user toneIndigo
```

## Components

### CLI and Environment

- [Vagrant CLI](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/cli.rb): `lib/vagrant/cli.rb`
- [Environment](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/environment.rb): `lib/vagrant/environment.rb`
- [Environment Config](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/config.rb): `lib/vagrant/config.rb`
- [Vagrantfile Loading](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/vagrantfile.rb): `lib/vagrant/vagrantfile.rb`

### Runtime Core

- [Action Middleware](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/action/primary_runner.rb): `lib/vagrant/action/primary_runner.rb`
- [Machine Lifecycle](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/machine.rb): `lib/vagrant/machine.rb`
- [Box Management](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/box_collection.rb): `lib/vagrant/box_collection.rb`
- [Box Metadata](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/box_metadata.rb): `lib/vagrant/box_metadata.rb`
- [Shared Helpers](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/shared_helpers.rb): `lib/vagrant/shared_helpers.rb`
- [Safe Environment](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/util/safe_env.rb): `lib/vagrant/util/safe_env.rb`
- [Version Utilities](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/version.rb): `lib/vagrant/version.rb`

### Machine Platforms

- [VirtualBox Provider](https://github.com/hashicorp/vagrant/blob/main/plugins/providers/virtualbox/action.rb): `plugins/providers/virtualbox/action.rb`
- [Storage Controllers](https://github.com/hashicorp/vagrant/blob/main/plugins/providers/virtualbox/model/storage_controller_array.rb): `plugins/providers/virtualbox/model/storage_controller_array.rb`
- [Disk Format Rules](https://github.com/hashicorp/vagrant/blob/main/plugins/providers/virtualbox/cap/validate_disk_ext.rb): `plugins/providers/virtualbox/cap/validate_disk_ext.rb`

### Guest Operations

- [SSH Communicator](https://github.com/hashicorp/vagrant/blob/main/plugins/communicators/ssh/communicator.rb): `plugins/communicators/ssh/communicator.rb`
- [Guest OS Support](https://github.com/hashicorp/vagrant/blob/main/plugins/guests/linux/guest.rb): `plugins/guests/linux/guest.rb`
- [Chef Provisioner](https://github.com/hashicorp/vagrant/blob/main/plugins/provisioners/chef/provisioner/chef_client.rb): `plugins/provisioners/chef/provisioner/chef_client.rb`
- [Synced Folders](https://github.com/hashicorp/vagrant/blob/main/plugins/synced_folders/nfs/synced_folder.rb): `plugins/synced_folders/nfs/synced_folder.rb`
- [Chef Provisioner Base](https://github.com/hashicorp/vagrant/blob/main/plugins/provisioners/chef/provisioner/base.rb): `plugins/provisioners/chef/provisioner/base.rb`
- [Chef Client Config](https://github.com/hashicorp/vagrant/blob/main/plugins/provisioners/chef/config/chef_client.rb): `plugins/provisioners/chef/config/chef_client.rb`

### Extensions and State

- [Plugin Manager](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/plugin/manager.rb): `lib/vagrant/plugin/manager.rb`
- [Plugin Dependencies](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/bundler.rb): `lib/vagrant/bundler.rb`
- [Plugin State](https://github.com/hashicorp/vagrant/blob/main/lib/vagrant/plugin/state_file.rb): `lib/vagrant/plugin/state_file.rb`
- [FTP Push](https://github.com/hashicorp/vagrant/blob/main/plugins/pushes/ftp/push.rb): `plugins/pushes/ftp/push.rb`
- [FTP Adapter](https://github.com/hashicorp/vagrant/blob/main/plugins/pushes/ftp/adapter.rb): `plugins/pushes/ftp/adapter.rb`

### Other components

- **Environment Developer**

## Connections

- Environment Developer → Vagrant CLI: runs commands
- Vagrant CLI → Environment: manages environments
- Environment → Vagrantfile Loading: loads configuration
- Vagrantfile Loading → Environment Config: provides settings
- Environment → Action Middleware: runs actions
- Action Middleware → Machine Lifecycle: manages lifecycle
- Machine Lifecycle → Box Management: uses boxes
- Box Management → Box Metadata: reads metadata
- Machine Lifecycle → VirtualBox Provider: runs on platform
- Storage Controllers → Disk Format Rules: validates format (evidence: `plugins/providers/virtualbox/model/storage_controller_array.rb`)
- Machine Lifecycle → SSH Communicator: communicates with guest
- Machine Lifecycle → Guest OS Support: uses guest support
- Machine Lifecycle → Chef Provisioner: runs provisioning
- Machine Lifecycle → Synced Folders: configures folders
- Plugin Manager → Plugin State: reads and updates (evidence: `lib/vagrant/plugin/manager.rb`)
- Plugin Manager → Plugin Dependencies: resolves plugins (evidence: `lib/vagrant/plugin/manager.rb`)
- Plugin Dependencies → Shared Helpers: uses helpers (evidence: `lib/vagrant/bundler.rb`)
- Plugin Dependencies → Safe Environment: uses environment (evidence: `lib/vagrant/bundler.rb`)
- Plugin Dependencies → Version Utilities: checks version (evidence: `lib/vagrant/bundler.rb`)
- Chef Provisioner → Chef Provisioner Base: inherits behavior (evidence: `plugins/provisioners/chef/provisioner/chef_client.rb`)
- Chef Provisioner → SSH Communicator: runs guest commands (evidence: `plugins/provisioners/chef/provisioner/chef_client.rb`)
- Chef Provisioner → Chef Client Config: uses configuration
- FTP Push → FTP Adapter: uploads files (evidence: `plugins/pushes/ftp/push.rb`)
