Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 36 ยท Networking and Synced Folders

SSH and Access

Connect to Vagrant machines with vagrant ssh, ssh-config, scp and editors; learn the config.ssh options, key handling, agent forwarding and WinRM for Windows.

Everything Vagrant does inside a Linux guest, it does over SSH: running provisioners, executing vagrant ssh -c, and giving you a shell. Understanding how that connection works helps you in three practical ways: you can use your own tools (a real SSH client, scp, VS Code Remote, Ansible) against the VM, you can solve "SSH auth failed" errors, and you can configure keys and agent forwarding safely. This lesson also explains how Windows guests are reached with WinRM instead.

How vagrant ssh connects

When a machine boots, Vagrant needs to reach its SSH server without asking for a password. Its trick:

  1. The box contains the well-known insecure key pair: a public key every Vagrant user can download, placed in ~vagrant/.ssh/authorized_keys.
  2. On the first vagrant up, Vagrant connects with the insecure key, generates a new random key pair unique to this machine, uploads the public half, and removes the insecure one. The private key is stored in .vagrant/machines/default/virtualbox/private_key.
  3. Every later connection uses that private key, over the forwarded port (127.0.0.1:2222 by default), as user vagrant.
sequenceDiagram
    participant V as Vagrant
    participant G as Guest sshd
    V->>G: connect with insecure key (first boot)
    V->>G: install new random public key
    V->>G: remove insecure key
    Note over V,G: later: key from .vagrant/machines/.../private_key
    V->>G: vagrant ssh / provisioners

Vagrant replaces the publicly known key at first boot, so the guest is not open to anyone who knows it.

This replacement is on by default (config.ssh.insert_key = true). If a box uses a different key, or you share one machine between several hosts, you may set config.ssh.insert_key = false. Doing so leaves the guest accepting the insecure key and is acceptable only on a private, local-only machine.

vagrant ssh-config

The command prints the connection details in the format of an OpenSSH client configuration:

CONSOLE
$ vagrant ssh-config
Host default
  HostName 127.0.0.1
  User vagrant
  Port 2222
  UserKnownHostsFile /dev/null
  StrictHostKeyChecking no
  PasswordAuthentication no
  IdentityFile /home/you/shop/.vagrant/machines/default/virtualbox/private_key
  IdentitiesOnly yes
  LogLevel FATAL

Everything else uses this. Connect with a plain SSH client, copy files with scp, run rsync:

CONSOLE
$ ssh -p 2222 -i .vagrant/machines/default/virtualbox/private_key vagrant@127.0.0.1
$ scp -P 2222 -i .vagrant/machines/default/virtualbox/private_key report.pdf vagrant@127.0.0.1:/tmp/

For a nicer workflow, append the output to your SSH config under a short name:

CONSOLE
$ vagrant ssh-config --host shop-dev >> ~/.ssh/config
$ ssh shop-dev
$ scp notes.txt shop-dev:/tmp/

Now editors that speak SSH, such as VS Code's Remote SSH extension, JetBrains Gateway or Ansible, can open shop-dev directly. If the VM is destroyed and recreated, the port or key may change, so update that block (or use vagrant ssh-config output again).

Running one command

CONSOLE
$ vagrant ssh -c "uname -a"
$ vagrant ssh -c "sudo systemctl restart nginx"
$ vagrant ssh web -c "tail -n 20 /var/log/nginx/error.log"

-c runs a single command, prints its output and returns its exit status, so you can use it in scripts and Makefiles. In multi-machine setups, pass the machine name before -c. Add -- -L 5432:localhost:5432 to pass extra options to the SSH client, for example for a tunnel.

The config.ssh options

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

  config.ssh.forward_agent = true       # use your host's SSH keys inside the VM
  config.ssh.keep_alive = true
  config.ssh.extra_args = ["-o", "ServerAliveInterval=30"]
  config.ssh.username = "vagrant"
  # config.ssh.private_key_path = ["~/.ssh/id_ed25519", "~/.vagrant.d/insecure_private_keys/vagrant.key.ed25519"]
  # config.ssh.insert_key = false
  # config.ssh.forward_x11 = true       # run GUI programs displayed on the host
end
  • forward_agent lets programs inside the VM, such as git clone [email protected]:..., use the keys loaded in the SSH agent of your host. Your private key never leaves the host. Use it only with VMs you trust, because root in the guest can use the forwarded agent while you are connected.
  • username and password change the login user; keys are strongly preferred over passwords.
  • private_key_path takes a list of keys to try; it is how you use your own key.
  • keep_alive and extra_args help with idle disconnects.
  • forward_x11 displays GUI apps from the guest on the host (needs an X server on Windows and macOS).
  • shell changes the login shell command.

Adding your own key for real access

If you want colleagues or tools to log in with their own keys, add it in a provisioner:

Ruby
pub = File.read(File.expand_path("~/.ssh/id_ed25519.pub")).strip
config.vm.provision "shell", inline: <<~SHELL
  mkdir -p /home/vagrant/.ssh
  grep -qF "#{pub}" /home/vagrant/.ssh/authorized_keys || echo "#{pub}" >> /home/vagrant/.ssh/authorized_keys
SHELL

Notice the grep -qF ... || guard so that repeated provisioning does not duplicate the key.

Windows guests: WinRM and RDP

Windows guests have no SSH server by default. Vagrant uses WinRM instead:

Ruby
config.vm.box = "gusztavvargadr/windows-11"
config.vm.communicator = "winrm"
config.winrm.username = "vagrant"
config.winrm.password = "vagrant"

vagrant powershell opens a remote PowerShell and vagrant rdp starts the Windows Remote Desktop client (RDP). Shell provisioners then run PowerShell instead of Bash (config.vm.provision "shell", inline: "Get-Service"). Windows boxes are large (many gigabytes) and slow to boot, so raise boot_timeout.

Troubleshooting SSH

Symptom Likely cause and fix
Timed out while waiting for the machine to boot Guest never became reachable. Set vb.gui = true, increase boot_timeout, check virtualization and network adapter 1
Authentication failure / Permission denied (publickey) Wrong key. Check config.ssh.private_key_path, that .vagrant was not deleted, or run vagrant reload
Connection refused sshd not running or the guest firewall blocks port 22
Remote host identification has changed A new VM reused port 2222; our generated config disables host key checks, a manual ssh does not. Use -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null or remove the line from known_hosts
Warning: Remote connection disconnect. Retrying... repeating The guest boots slowly, or a network problem; wait or enable the GUI
private_key permissions are too open On Windows/macOS shared folders; keep the project on a real disk, or copy the key

You can see the full conversation with VAGRANT_LOG=debug vagrant ssh 2>&1 | more.

Reading ssh-config output with Ruby

The runnable stand-in parses the output of vagrant ssh-config and builds the matching ssh and scp commands. This is the kind of helper you might put into a Rakefile or a trigger. It is plain Ruby, so it works here without Vagrant.

Ruby Parse ssh-config and build commands (Ruby)

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.

Security habits

  • Treat the SSH port forward like any other port: it is bound to 127.0.0.1 by default for the SSH rule, so it is only reachable locally.
  • Do not publish a VM with the insecure key (insert_key = false) on a public network.
  • Do not commit .vagrant/ (it contains the private key).
  • Use forward_agent sparingly.
  • Change the default vagrant/vagrant password on machines others can reach.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Vagrant do with the insecure key on the first boot?

    With insert_key enabled (the default), the publicly known key is swapped for a private, per-machine key.
  2. 2. Which command prints SSH client settings so other tools can connect?

    vagrant ssh-config prints a Host block with HostName, Port, User and IdentityFile.
  3. 3. What does config.ssh.forward_agent = true allow?

    Agent forwarding lets the guest authenticate with keys held by your host's agent, for example to clone a private repository.
  4. 4. How does Vagrant usually connect to a Windows guest?

    Windows guests normally use WinRM; vagrant powershell and vagrant rdp are the interactive options.

Summary

  • vagrant ssh connects over a forwarded port with a per-machine key generated at first boot.
  • vagrant ssh-config provides everything needed to use ssh, scp, VS Code Remote or Ansible against the VM.
  • config.ssh.* sets users, keys, agent forwarding and keep-alive; add your own key with a guarded provisioner.
  • Windows guests use WinRM and RDP instead of SSH.
  • Keep .vagrant/ private and avoid exposing VMs that still use default credentials.

Next: Multi-machine Vagrantfiles