This quick tip will help you get up and running with a brand new Homestead Improved Vagrant VM.

  • to find out about Vagrant and why you should use it, see this post.
  • Homestead Improved is based on Homestead, but has the added benefit of not forcing you to deal with SSH keys, doesn’t get installed globally, is more cross-platform friendly, and comes with a helper script to auto-configure the shared folders.
  • I recommend creating a new Homestead Improved VM for every new project, and this tutorial will follow such a practice.


You need:

The tutorial assumes you’ll be using a bash-like terminal; Git Bash if on Windows (comes with Git Tools).

Getting Started

The following 3 commands are all that’s necessary for starting a new Homestead Improved VM instance on any operating system (obviously, replace my_project with your desired folder name):

git clone my_project
cd my_project; mkdir Laravel/public
bin/ # this is optional!

The first two clone the project and enter the newly created folder.

The third one executes the folderfix script which shares the project’s folder with the Code folder inside the VM. That means you can edit files inside the project folder (my_project) and they’ll be reflected inside the VM, and vice versa. This allows you to use your main computer’s text editor / IDE to edit the files of a project inside the VM. You can also do this manually by editing the folders field in Homestead.yaml.

Add New Sites

There are two steps to adding every new site into a Homestead VM.

Step 1: Set up etc/hosts

etc/hosts is a file present on every operating system. On Windows, it’s in C:/Windows/System32/drivers/etc/, on OS X and Linux it’s in /etc/hosts. Edit it as an administrator (one easy way to do this is to run a text editor like Sublime Text as Administrator) and add in an entry like this for every application you intend to develop:

Replace with your desired domain name, or just add in multiple domain names. For example, I have this in my own hosts file:

This means I can access each of these domains in the browser via, or, etc.

Step 2:

For every domain you defined in the above step, you need to add a sites mapping. Open the file Homestead.yaml in the cloned copy of the Homestead Improved repo, and add a pair for each. The default is:

    - map:
      to: /home/vagrant/Code/Laravel/public

This means (if you added it to etc/hosts in the step above) will look for index.php in the folder /home/vagrant/Code/Laravel/public inside the VM. You can add this file while outside the VM, too, by simply creating a Laravel/public folder in the root of the cloned Homestead Improved VM, and adding index.php in there – this is the same as adding it inside the VM into the aforementioned location, because the folders are shared.

You add new sites by adding new map/to pairs (as many as you wish):

    - map:
      to: /home/vagrant/Code/Laravel/public
    - map:
      to: /home/vagrant/Code/test

Booting Up and SSHing

Once all the sites have been added, boot the VM with:

vagrant up

Go inside the VM with:

vagrant ssh

Once inside, you can use the VM as if it were a regular production or development linux server.

Ports and Blackfire

Homestead comes with Blackfire pre-installed. It’s a very powerful profiler for PHP apps which inspects code into great detail and draws complexity graphs which help you speed up your apps. If you have an account, uncomment the blackfire lines in Homestead.yaml and put your data in there.

If you want to open additional ports, like for example port 5000 for Heroku, uncomment the ports part of Homestead.yaml and add in the values, like so:

    - send: 5000
      to: 5000

Database Access

Homestead comes with MySQL pre-installed. Its user is homestead and its password is secret. To connect to it from the outside operating system (Homestead does not have PhpMyAdmin installed), use a tool like Sequel Pro or the MySQL Workbench and specify the following parameters:

  • server:
  • user: homestead
  • pass: secret
  • port: 33060

The default homestead database should show up when you connect.


You should now be able to quickly set up a new VM instance for every new app you intend to build. This will allow you to seamlessly follow along with all our tutorials. Please let me know in the comments below if any of the above steps are unclear or could/should be simplified.

Bruno is a coder from Croatia with Master’s Degrees in Computer Science and English Language and Literature. He’s the editor of SitePoint’s PHP channel and a developer evangelist for He avoids legacy code like the plague and when picking projects makes sure they’re as cutting edge as possible. He’s a treadmill desk enthusiast and active (board)gamer who sometimes blogs.

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.

  • dmathisen

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

    • Bruno Skvorc

      Cheers. We’ve dealt with PuPHPet before (see 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.

      • 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.

  • saim

    Great tutorial! I’m new to Vagrant and Laravel Homestead. Been using Laravel for about a year. Server booted up first go. Thanks.

    I assumed you then install laravel through composer to $DIR/myapp. Then you can visit the welcome page at however I ended up with “No input file specified.”

  • 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/` 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!

      • Bruno Skvorc

        No problem, glad you liked it!

        • Yoram

          Hi Bruno, how do I view this error log? I’m pretty new to Nginx and also receiving “No input specified”, even after installing laravel via composer. Any help would be greatly appreciated, quite stuck atm… :/

          • Bruno Skvorc

            No input specified means that there simply is no index.php file at the location mapped in your folders fields. The log file is as /var/www/log/nginx inside your VM (go inside it with vagrant ssh)

    • 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”.

      • nelson

        I’m having the same problem. I’m so close!!! But there is no Laravel directory in /code

        Any advice?

        • Bruno Skvorc

          Create one.

      • Bruno Skvorc

        Gentlemen, this is just a VM. The fact that the same person who made Laravel made it just unfortunate – it has nothing to do with Laravel. You install Laravel into this the same way you install anything else into it – just install into the folder specified in your folders field, make sure the index.php file is in that folder. If the folder doesn’t exist, create it, simple as that.

  • 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.

  • Jasper van der Hoeven

    I followed the steps on my windows machines but got a “/vagrant/scripts/ no such file or directory” message. I solved it by running:

    vagrant ssh

    sudo su –

    ln -ls /home/vagrant/Code/scripts scripts

    After that the error was gone. Hope this helps people with the same problem.

    Also make sure you enable the virtualisation setting in your BIOS to prevent “default: Error: Connection timeout. Retrying…” messages.

  • 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.

    • Bruno Skvorc

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

      • 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:
        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…

        • Bruno Skvorc

          Do you have virtualization enabled in your BIOS?

  • 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

    • Bruno Skvorc

      They’re identical. The improved box uses the original box.

  • Tanveer

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

  • El Rhazal Oumaima

    hi ! thanks for that awesome tetorial =)
    please i need a help … :(
    i followed alll the steps , and everything went good , until o arrived to the last step ==> , but it says :
    Not Found
    HTTP Error 404. The requested resource is not found.

    Please help me , what should i do ?

  • Sanjay Ojha

    For me wired thing is happening, Bruno can you help me.
    During vagrant up my Homestead.yml have following :

    ip: “”
    memory: 1024
    cpus: 1

    – map: D:/app
    to: /home/vagrant/code
    – map: D:/app/laravel
    to: /home/vagrant/code/laravel
    – map: D:/app/myapp
    to: /home/vagrant/code/myapp

    – map:
    to: /home/vagrant/code/laravel/public
    – map:
    to: /home/vagrant/code/myapp

    – key: APP_ENV
    value: local

    I was assuming that will serve the content from “D:/app” from my host machine which is mapping to ” /home/vagrant/code” on my guest machine.

    I also assumed that will server content from “D:/app/laravel/public” from my host machine but here mapping is from “D:/app/laravel/” to “/home/vagrant/code/laravel”, Which I think is fine as I have defined in site configuration.

    What happening is is mapping to “D:/app/laravel/public” and or is throwing error “server not found”. Also is serving content from to “D:/app/laravel/public” while is working fine.

    So what could be the real cause of this mismatches ?

    • Bruno Skvorc

      You shouldn’t use in the URL, use only virtualhost domains – I can’t help you with the IP since it’s unpredictable what will get served first. Please provide the full URLs and full errors of each.

  • Steve

    Perhaps an extra tip (I really hate those port numbers): Use socat! :) I’m on macos so I can’t be sure it will work everywhere, but here’s what I do: `sudo ifconfig lo0 alias`. This gives the loopback interface an extra IP. Then you can socat port 80 on that one to whatever your vm webserver is running on. Eg: `sudo socat TCP4-LISTEN:80,bind=,fork TCP4: &`. (I’m assuming the same port as the article here). Final step: Instead of using in the hosts file, use and pronto, no more port number. Obviously the alias and socat need to be ran every time after you reboot, but still. Also: the IP I used is just something that I chose. You can pick whatever doesn’t interfere with your regular network settings. Hope this helps someone.

    • Bruno Skvorc

      No need, just put the IP of the VM into hosts instead of and problem solved

  • Ryan Kang

    Thanks for sharing your great tutorial. I followed your guide and worked fine. I have a question though. Laravel documentation says that I will have to put the ip address on hosts file. However, you suggest which is localhost. Is there any particular reason why you
    put this localhost ip address?

    • Bruno Skvorc

      Outdated instructions, will fix. Either is fine – if you put localhost, your URLs will have to have :8000, otherwise they won’t.

  • jagtar s mundey

    I followed the same and was able to setup homestead quickly. Thanks for the easy setup way. I could not achieve same using official setup way.

    Just a note maybe for a noob like me is that composer should be run from within vm.

    I’m still wondering why actual homestead git offers with those src and scripts which are sort of not present in homestead_improved.

  • Nikees

    I did everything a couple of times with the same result:


    I disabled my firewall without result

    yaml file:

    ip: “”

    memory: 2048

    cpus: 1

    provider: virtualbox


    – map: .

    to: /home/vagrant/Code


    – map:

    to: /home/vagrant/Code/Laravel/public


    – key: APP_ENV

    value: local

    log from vagrant up command:
    C:homestead>vagrant up

    Bringing machine ‘default’ up with ‘virtualbox’ provider…

    ==> default: Importing base box ‘laravel/homestead’…

    ==> default: Matching MAC address for NAT networking…

    ==> default: Checking if box ‘laravel/homestead’ is up to date…

    ==> default: Setting the name of the VM: homestead_default_1437742901421_71372

    ==> default: Clearing any previously set network interfaces…

    ==> default: Preparing network interfaces based on configuration…

    default: Adapter 1: nat

    default: Adapter 2: hostonly

    ==> default: Forwarding ports…

    default: 80 => 8000 (adapter 1)

    default: 5000 => 5000 (adapter 1)

    default: 3306 => 33060 (adapter 1)

    default: 5432 => 54320 (adapter 1)

    default: 22 => 2222 (adapter 1)

    ==> default: Running ‘pre-boot’ VM customizations…

    ==> default: Booting VM…

    ==> default: Waiting for machine to boot. This may take a few minutes…

    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: Remote connection disconnect. Retrying…


    default: Vagrant insecure key detected. Vagrant will automatically replace

    default: this with a newly generated keypair for better security.


    default: Inserting generated public key within guest…

    default: Removing insecure key from the guest if its present…

    default: Key inserted! Disconnecting and reconnecting using new SSH key…

    ==> default: Machine booted and ready!

    ==> default: Checking for guest additions in VM…

    ==> default: Setting hostname…

    ==> default: Configuring and enabling network interfaces…

    ==> default: Mounting shared folders…

    default: /home/vagrant/Code => C:/homestead

    ==> default: Running provisioner: shell…

    default: Running: inline script

    ==> default: stdin: is not a tty

    ==> default: Updating to version c6cc6dd6070871f4b198ed39f76dd8047c116b02.

    ==> default: Downloading: Connecting…

    ==> default:

    ==> default: Downloading: 100%

    ==> default:

    ==> default:

    ==> default: Use composer self-update –rollback to return to version c43a39f733


    ==> default: Running provisioner: shell…

    default: Running: inline script

    ==> default: stdin: is not a tty

    ==> default: bash: /vagrant/scripts/ No such file or directory

    The SSH command responded with a non-zero exit status. Vagrant

    assumes that this means the command failed. The output for this command

    should be in the log above. Please read the output to determine what

    went wrong.


    I so like to learn this framework, but I lost 3 hours allready and I didn’t started yet… so frustrating everytime I wanted to learn something new. Please anyone an idea of what may going wrong?


    • Bruno Skvorc

      When you clone homestead improved, inside the folder run: sed -i ” “s@map: .@map: $PWD@g” Homestead.yaml

      Then try running vagrant up again.

  • anonymous

    $ vagrant up

    ==> default: Successfully added box ‘laravel/homestead’ (v0.2.7) for ‘virtualbox’!
    There are errors in the configuration of this machine. Please fix
    the following errors and try again:

    * The host path of the shared folder is missing: /var/www/myapp
    * The host path of the shared folder is missing: /var/www/myapp2

    how to fix the above?

    • Bruno Skvorc

      Make sure the folders exist.

  • Bruno Skvorc

    Note to all: the comments below are now probably irrelevant, as the article has been almost completely revamped.

  • Adil Shahzad

    I’ve installed everything but when i try to run the following commands
    vagrant up – It boots the vm which is okay but when i run a command
    vagrant ssh – It shows the following message:

    `ssh` executable not found in any directories in the %PATH% variable. Is an
    SSH client installed? Try installing Cygwin, MinGW or Git, all of which
    contain an SSH client. Or use your favorite SSH client with the following
    authentication information shown below:

  • Nikhil Dhiman

    that’s gr8,, as an s/w engineer you always have to see ur code as legacy and try to replace it with current cutting edge technologies.. But to do that how you actually write code, that’s make easy to migrate.

Related books & courses
Available now on SitePoint Premium

Preview for $1