Use Vagrant to manage Proxmox virtual machines
Clone or download
#3 Compare This branch is 13 commits ahead of telcat:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Vagrant Proxmox Provider

This is a Vagrant plugin that adds a Proxmox provider to Vagrant, allowing Vagrant to manage and provision Proxmox virtual machines.

About this Fork

The primary motivation for this fork was to support the author's goals for managing Linux Containers (LXC) hosted in Proxmox. As such, this README and patches in this fork are tailored for this purpose. If you are interested in the original project, refer to the upstream project. With this said, this fork has the following goals:

  • Provide instructions for building an installing the plugin locally. Unlike the original, this plugin must be built and installed locally. It is not available for installation via RubyGems. Proxmox 4.x APIs.
  • Merge pull request #26 and #32]
  • Provide detailed instructions on configuring Proxmox to use a custom Vagrant-compatible CentOS 7 container.


  • Vagrant 1.8+
  • Ruby 2.4.1
  • Promox 4.4

Building and Installing the Plugin (OS X)

The author's local development environment is an OS X workstation. If you are on OS X, ensure that you have Homebrew installed.

  1. Install rbenv so that you can manage multiple versions of Ruby.

     $ brew update
     $ brew install rbenv
  2. Add the rbenv shim to your PATH. It’s recommended that you add it to your Bash profile (~/.bash_profile).

     export PATH
  3. Source ~/.bash_profile to pick up your updated PATH.

     $ . ~/.bash_profile
  4. Install Ruby 2.4.1 and add all the shims.

     $ rbenv install 2.4.1
     $ rbenv rehash
  5. Ensure that the current active version is set to 2.4.1.

     $ rbenv versions
     * system (set by /Users/gaston/.rbenv/version)
  6. Verify that rbenv is actually using Ruby to 2.4.1.

     $ ruby -v
     ruby 2.4.1p111 (2017-03-22 revision 58053) [x86_64-darwin15]
  7. Clone this project and build the plugin.

     $ git clone
     $ cd vagrant-proxmox
     $ rbenv local 2.4.1
     $ gem install bundler
     $ bundle install
     $ rake build
  8. Uninstall the vagrant-proxmox plugin if exists and install the plugin locally.

     $ vagrant plugin uninstall vagrant-proxmox
     $ vagrant plugin install pkg/vagrant-proxmox-0.0.10.gem
     $ vagrant plugin list
  9. Add the dummy Vagrant box for this provider.

     $ vagrant box add dummy dummy_box/

Note: For ongoing development, run the following to rebuild and reinstall the plugin. $ rake build && vagrant plugin uninstall vagrant-proxmox && vagrant plugin install pkg/vagrant-proxmox-0.0.10.gem

Create Vagrant-compatible Container

Refer to the Add a CentOS 7 Container Image section on my blog post for instructions.

Add a Promox User (Optional)

Refer to the Add a Promox User sectopm on my blog post for instructions.

Create a Vagrantfile and Provision

On your local workstation, create a Vagrantfile. Simply change:

  • config.ssh.private_key_path - This should point to the private key on your local workstation that was created earlier.
  • proxmox.endpoint - This should be updated with the IP or hostname of your Proxmox server.
  • - The cidr_block is required. Most users will likely use '/24' if they are using netmask.
Vagrant.configure('2') do |config|

    config.ssh.private_key_path = '/Users/gaston/vagrant-keys/vagrant'
    config.vm.hostname = 'centos7-proxmox'

    config.vm.provider :proxmox do |proxmox|
        # Useful for debugging unencrypted request/response with stunnel+Wireshark
        #proxmox.endpoint = 'http://localhost:8006/api2/json'
        proxmox.endpoint = ''
        proxmox.user_name = 'vagrant@pve'
        proxmox.password = 'vagrant'
        proxmox.vm_id_range = 900..910
        proxmox.vm_name_prefix = 'vagrant_'
        proxmox.openvz_os_template = 'local:vztmpl/centos-7-base_20161225_amd64.tar.xz'
        proxmox.vm_type = :lxc
        proxmox.vm_memory = 1024
        proxmox.vm_storage = 'local-lvm'
        proxmox.vm_disk_size = '50G'

    config.vm.define :box, primary: true do |box| = 'dummy' :public_network, ip: '', cidr_block: '/24', interface: 'eth0', bridge: 'vmbr0', gw: ''


Provision a VM.

    $ vagrant up --provider=proxmox 

If you run into issues, add the --debug flag.