Quick Tip: Get a Homestead Vagrant VM Up and Running


This quick tip will show you how to get a working Homestead Vagrant Box up and running in no time. Note, this quick tip is based on homestead_improved, my own version of Homestead which doesn’t ask you to deal with SSH keys and automatically forwards port 5000 in order to accommodate Heroku’s Foreman tool.

Relevant articles (optional additional reading):

Step 1 – prerequisites

Make sure you have the newest Vagrant and VirtualBox installed for your operating system.

If on Windows, also install Git Bash via git tools.

Step 2 – cloning

Using a command line (terminal in *nix, git bash on Windows), cd into the folder where you’d like your virtual box to run from. For example, I use Windows as my host OS and have all my Vagrant things on D:\VM\vagrant_boxes.

Run the following command ($DIR is the name of the directory you want your VM to reside in, e.g. “Homestead”):

git clone https://github.com/Swader/homestead_improved $DIR

Step 3 – set up sites and folders

Now cd into $DIR, open Homestead.yaml and change your “folders” section and/or your “sites” section.

“sites” adds new virtual hosts for Nginx, so if you need to access multiple apps on one VM, add them here:

    - map: myapp.com
      to: /home/vagrant/Code/myapp/public
    - map: myapp2.com
      to: /home/vagrant/Code/myapp2/public

Under “folders”, “map” is the location of the folder on the host machine and “to” is the location of the folder in the VM.

For example, if you keep your code in /var/www/myapp and want to test/host it inside the VM, you could change the folders to this:

    - map: /var/www/myapp
      to: /home/vagrant/Code/myapp

To add more of these bindings, just add a new map-to block underneath the current one, like so:

    - map: /var/www/myapp
      to: /home/vagrant/Code/myapp
    - map: /var/www/myapp2
      to: /home/vagrant/Code/myapp2

Note: Homestead Improved is configured to automatically set your current folder as shared with the /Code folder inside your VM, so you generally don’t need to change the “folders” block. However, some OSs fail to recognize “.” as “current folder” and will throw errors during provisioning (Windows <8 and Mac OS X) so you’ll have to change the “.” to an absolute path to the folder you want to share, as described above. To map the current folder to this location, you can use this simple command: sed -i '' "s@map\: \.@map\: $PWD@g" Homestead.yaml

Step 4 – hosts

Open your host machine’s hosts file and add a line for each of your added sites listed under the aforementioned sites block: myapp.com myapp2.com

For instructions on how to edit your hosts file on any given OS, see here.

Step 5 – vagrant up

Run vagrant up while inside $DIR, and when the procedure is finished, run vagrant ssh to enter the VM through SSH.

You can now access your sites through the browser on your host machine via http://myapp.com:8000/ and http://myapp2.com:8000/. You can connect to MySQL from the host machine’s Workbench or any other database management tool by selecting the following connection parameters:

  • port: 33060
  • host:
  • username: homestead
  • password: secret

That’s it.

Get your free chapter of Level Up Your Web Apps with Go

Get a free chapter of Level Up Your Web Apps with Go, plus updates and exclusive offers from SitePoint.

  • https://twitter.com/dmathisen36 dmathisen

    Great post, and I know this is setting up Homestead, but I used a similar Vagrant / VirtualBox setup and used PuPHPet (https://puphpet.com/) to set up our VM. Worked out really well.

    • http://www.bitfalls.com/ Bruno Skvorc

      Cheers. We’ve dealt with PuPHPet before (see http://www.sitepoint.com/tag/puphpet/) but it’s been known to fail rather often. Homestead is more standardized, being Laravel-endorsed, and always works. But definitely, tools like PuPHPet and Vaprobash are priceless when you need to change things up.

      • https://twitter.com/dmathisen36 dmathisen

        Yeah, I’ve had issues with version upgrades, etc. So it’s definitely not perfect. I’m not familiar with Homestead… will have to check it out.

  • http://www.bitfalls.com/ Bruno Skvorc

    You should install Laravel via Composer into the Code folder, did you do that? If you did, not sure, it should work, I use this procedure every day.

    See the error logs of Nginx inside Homestead with `sudo less /var/log/nginx/myapp.com-error.log` and press SHIFT+G to go to the bottom of the file. It should tell you which path it’s looking for the input file in.

    • saim

      Hi Bruno,

      My mistake – I had incorrectly declared my ‘folders’ path. Thank you for your quick reply and again, the great tutorial!

      Thanks again!

      • http://www.bitfalls.com/ Bruno Skvorc

        No problem, glad you liked it!

    • Tanveer

      how should i install laravel via composer into the code folder and where it is mentioned in the article? i am having the “no input file specified”.

  • Phyo Thu Aung

    when I do “vagrant up”, I got an error saying “the shared folder guest path must be absolute”. any idea why?

  • DaHaiz

    hi bruno! first thanks for your efforts in homestead improved and for this nice tutorial. got only a little question: in your tutorial you start a new project from scratch and cloned your repo, but how would you integrate homestead improved in an existing app (where we already have a git repo)? Thanks in advance very much for your answer,

  • Nicholas Loomans

    I get “The box ‘laravel/homestead’ could not be found.” when running with the latest version of Vagrant for Ubuntu 14.04. The solution was to manually download the latest version from Vagrant and install that, then `vagrant up` worked.

  • http://w3guy.com Agbonghama Collins

    Am using Windows, how will I do the folder/path mapping in homestead.yaml ? Mind you, with Windows file path varies from Linux.

    Got vagrant working but can’t get passed the path mapping.

    • http://www.bitfalls.com/ Bruno Skvorc

      Works out of the box for me, I’m on Windows, too. What’s the problem?

      • http://w3guy.com Agbonghama Collins

        I installed homestead in C:VMvagrant_boxesHomestead

        I created a htdoc folder relative to the Homestead folder above where all my project will be hosted.

        Here is my homestead.yaml file.

        ip: “”
        memory: 2048
        cpus: 1

        – map: C:VMvagrant_boxesHomesteadhtdoc
        to: /home/vagrant/Code

        – map: homestead.app
        to: /home/vagrant/Code/hybrid

        – key: APP_ENV
        value: local

        Mind you, i do get the following errors after doing vagrant up.

        default: Waiting for machine to boot. This may take
        default: SSH address:
        default: SSH username: vagrant
        default: SSH auth method: private key
        default: Warning: Connection timeout. Retrying…
        default: Warning: Connection timeout. Retrying…
        default: Warning: Connection timeout. Retrying…
        default: Warning: Connection timeout. Retrying…

  • Julius Koronci

    Too bad that Homestead uses Nginx..I tried to run a symfony project but ended up playing with how to replace the .htaccess file..otherwise a great post..although I couldn’t run the imporved box on Ubuntu so had the use the original from laravel

  • Tanveer

    Most likely you incorrectly declared ‘folders’ path in Homestead.yaml file.