Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Your First Vagrant Machine

Create, boot, log into and destroy your first Vagrant virtual machine with vagrant init, up, ssh and destroy, and understand what happens at each step.

Time to build something. In this lesson you will create a project folder, generate a Vagrantfile, start a virtual machine, log into it, see your project folder inside it, and finally throw it all away. Along the way you will learn what Vagrant prints during vagrant up and what each stage means. The terminal output shown here is typical for VirtualBox; the exact lines vary by version and box.

Step 1: a project folder and a Vagrantfile

Every Vagrant environment lives in a folder. Create one and generate a starter file with vagrant init, passing the name of a box:

CONSOLE
$ mkdir hello-vagrant
$ cd hello-vagrant
$ vagrant init bento/ubuntu-24.04
A `Vagrantfile` has been placed in this directory. You are now
ready to `vagrant up` your first virtual environment! Please read
the comments in the Vagrantfile as well as documentation on
`vagrantup.com` for more information on using Vagrant.

vagrant init only writes a file. It starts nothing and downloads nothing. The generated Vagrantfile is full of commented-out examples; with the comments removed, the live part is just this:

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"
end

The "2" is the configuration version; every modern Vagrantfile uses "2". If you want a file without the comments, run vagrant init --minimal bento/ubuntu-24.04.

Step 2: vagrant up

CONSOLE
$ vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Box 'bento/ubuntu-24.04' could not be found. Attempting to find and install...
    default: Box Provider: virtualbox
    default: Box Version: >= 0
==> default: Loading metadata for box 'bento/ubuntu-24.04'
==> default: Adding box 'bento/ubuntu-24.04' (v202508.03.0) for provider: virtualbox
    default: Downloading: https://vagrantcloud.com/...
==> default: Successfully added box 'bento/ubuntu-24.04' (v202508.03.0) for 'virtualbox'!
==> default: Importing base box 'bento/ubuntu-24.04'...
==> default: Matching MAC address for NAT networking...
==> default: Setting the name of the VM: hello-vagrant_default_1731401234567_12345
==> default: Forwarding ports...
    default: 22 (guest) => 2222 (host) (adapter 1)
==> default: Booting VM...
==> default: Waiting for machine to boot. This may take a few minutes...
    default: SSH address: 127.0.0.1:2222
    default: SSH username: vagrant
    default: SSH auth method: private key
==> default: Machine booted and ready!
==> default: Mounting shared folders...
    default: /vagrant => /home/you/hello-vagrant

Read this as a story of the lifecycle:

  1. Pick the provider and machine. A single-machine Vagrantfile has one machine called default.
  2. Fetch the box if it is not cached yet. This is the slow part, once per box version. The next project that uses the same box skips it.
  3. Import the box: the provider makes a fresh copy for this machine. The box itself is never modified.
  4. Configure hardware: network adapters, a forwarded SSH port (guest 22 to a free port on the host, 2222 by default), the synced folder.
  5. Boot and wait for SSH. Vagrant tries to open an SSH connection until it works, authenticating with an automatically created key.
  6. Mount shared folders and run provisioners (none yet).
sequenceDiagram
    participant You
    participant Vagrant
    participant Provider
    You->>Vagrant: vagrant up
    Vagrant->>Vagrant: find or download box
    Vagrant->>Provider: import box, set hardware
    Provider-->>Vagrant: VM created
    Vagrant->>Provider: start VM
    Vagrant->>Vagrant: wait for SSH
    Vagrant->>Provider: mount synced folders
    Vagrant-->>You: machine ready

What vagrant up does on a first run.

Step 3: log in

CONSOLE
$ vagrant ssh
Welcome to Ubuntu 24.04.2 LTS (GNU/Linux 6.8.0-64-generic x86_64)
vagrant@vagrant:~$ whoami
vagrant
vagrant@vagrant:~$ ls /vagrant
Vagrantfile
vagrant@vagrant:~$ sudo whoami
root

You are inside the VM as the user vagrant, who can run sudo without a password. Your project folder is mounted at /vagrant, so the Vagrantfile appears there. This is two-way: create a file on your host in the project folder, and it shows up in the guest immediately; the reverse also works.

Try this to see the sync working:

CONSOLE
vagrant@vagrant:~$ echo "hello from the guest" > /vagrant/note.txt
vagrant@vagrant:~$ exit
$ cat note.txt
hello from the guest

Leave the session with exit or Ctrl-D. The VM keeps running in the background.

Step 4: stop and clean up

CONSOLE
$ vagrant halt        # graceful shutdown, disk kept
$ vagrant up          # start again, fast: no download, no import
$ vagrant destroy -f  # delete the VM and its disk (-f skips the question)

After destroy, the VM is gone but your Vagrantfile and project files remain, and the box stays cached. Run vagrant up again and you get a brand-new machine in seconds, because only the import step is repeated. That repeatability is the whole point.

What vagrant init and .vagrant created

After the first up, the folder looks like this:

TEXT
hello-vagrant/
  Vagrantfile
  .vagrant/
    machines/default/virtualbox/id     # the provider's ID for this VM
    machines/default/virtualbox/private_key

.vagrant is Vagrant's local state. It links this folder to the VM. Do not commit it (add .vagrant/ to .gitignore), and do not delete it while the VM still exists, or Vagrant will lose track of the machine and the VM will be orphaned in VirtualBox.

Here is a tiny runnable model of the lifecycle as a state machine. It is a stand-in written in Ruby, not Vagrant, but it enforces the same rules you just saw: you cannot ssh into a machine that is not running, and destroy always ends in a non-created state.

Ruby Machine lifecycle as a state machine (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Common first-run problems

  • Nothing happens for minutes after "Waiting for machine to boot": the VM is booting but SSH is unreachable. Set config.vm.boot_timeout higher, or enable the VM GUI (vb.gui = true) to see the console.
  • "A VirtualBox machine with the same name already exists": you deleted .vagrant but not the VM. Remove it in VirtualBox or VBoxManage unregistervm.
  • Port 2222 already in use: Vagrant detects collisions for the SSH port and picks another automatically; see SSH and access.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does vagrant init do?

    vagrant init only writes a Vagrantfile. vagrant up is the command that downloads and boots.
  2. 2. After vagrant destroy, which of these still exists?

    Destroy removes the VM but keeps the Vagrantfile, your project files and the downloaded box.
  3. 3. Where does your project folder appear in the guest by default?

    The folder with the Vagrantfile is synced to /vagrant.
  4. 4. Which command shuts the VM down but keeps its disk?

    halt performs a graceful shutdown; the disk remains, so a later up is quick.

Summary

  • vagrant init <box> writes a Vagrantfile; vagrant up downloads the box, creates, boots and configures the VM.
  • vagrant ssh logs you in as the vagrant user, with passwordless sudo.
  • Your project folder is shared as /vagrant in both directions.
  • halt stops, up restarts, destroy deletes the VM but keeps the box cache.
  • .vagrant/ is local state: keep it out of version control.

Next: CLI Essentials and the Machine Lifecycle