Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท Networking and Synced Folders

Forwarded Ports

Reach services in your Vagrant VM from the host with forwarded ports: syntax, host_ip, auto_correct, protocols, privileged ports, collisions and the NAT behind it.

Your web app runs inside the virtual machine on port 3000, but you want to open it in the browser on your own computer. By default the VM sits behind a virtual router (NAT) that hides it, so the browser cannot reach it. The simplest solution is a forwarded port: a rule that says "traffic arriving at port 8080 on my computer goes to port 80 in the VM". This lesson explains the option set, what the NAT does, and how to avoid collisions and accidental exposure.

The basic rule

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"
  config.vm.network "forwarded_port", guest: 80, host: 8080
end

After vagrant up, http://localhost:8080 on the host reaches whatever listens on port 80 inside the guest. You can list the active rules at any time:

CONSOLE
$ vagrant port
The forwarded ports for the machine are listed below. Please note that
these values may differ from values configured in the Vagrantfile if the
provider supports automatic port collision detection and resolution.

    22 (guest) => 2222 (host)
    80 (guest) => 8080 (host)

The SSH rule (22 to 2222) is created by Vagrant itself; it is how vagrant ssh connects.

flowchart LR
    B["Browser on host: localhost:8080"] --> NAT["NAT / port forwarding rule"]
    NAT --> G["Guest port 80 (nginx)"]

One rule, one direction: host port to guest port.

Options

Option Meaning Default
guest: Port inside the VM required
host: Port on your computer required
host_ip: Address on the host that listens all interfaces (0.0.0.0)
guest_ip: Address inside the guest that receives all
protocol: "tcp" or "udp" "tcp"
auto_correct: Pick another host port when it is taken false (but see below)
id: A name for the rule, to override it later

Bind to localhost on purpose. Without host_ip, the forwarded port is reachable from every machine on your network (office Wi-Fi, a coffee shop). A development database or an admin panel does not belong on the internet. Prefer:

Ruby
config.vm.network "forwarded_port", guest: 5432, host: 5432, host_ip: "127.0.0.1"
config.vm.network "forwarded_port", guest: 53, host: 5353, protocol: "udp"

An open forwarded port with an unprotected service (a database without password, a debug interface, a Jupyter notebook) is a real risk on shared networks. Always set host_ip: "127.0.0.1" unless you deliberately want to share the service.

Collisions and auto_correct

Two things cannot both listen on host port 8080. If another program, or another Vagrant machine, already uses it, vagrant up stops with an error:

TEXT
Vagrant cannot forward the specified ports on this VM, since they
would collide with some other application that is already listening
on these ports. The forwarded port to 8080 is already in use on the host machine.

With auto_correct: true Vagrant silently picks another free host port (2200 to 2250 by default) instead:

Ruby
config.vm.network "forwarded_port", guest: 80, host: 8080, auto_correct: true

Then run vagrant port to see the port that was really chosen. The SSH rule always has auto_correct turned on, which is why a second Vagrant machine gets 2200 and not an error. For services you tell colleagues about, a fixed port is clearer; use auto_correct for tools where the exact number does not matter, and set the range with config.vm.usable_port_range = 8000..8999.

Ports below 1024

On Linux and macOS, only root may listen on ports below 1024 on the host, so host: 80 fails for a normal user. Use a high port (8080) and, if you need the plain http://myapp.test, put a local reverse proxy on port 80 or use a private network address, see private networks. On Windows, port 80 may already be taken by IIS or another program.

Several rules from a list

Since the Vagrantfile is Ruby, a table drives many rules:

Ruby
{ 80 => 8080, 443 => 8443, 5432 => 15432, 6379 => 16379 }.each do |guest, host|
  config.vm.network "forwarded_port", guest: guest, host: host, host_ip: "127.0.0.1", auto_correct: true,
    id: "port-#{guest}"
end

The id makes each rule individually addressable: a later Vagrantfile layer can replace the rule by using the same id.

Checking that it works

  1. Is the service listening inside the guest on the right address? Run vagrant ssh -c "ss -tlnp". A service listening only on 127.0.0.1 inside the guest is still reachable through forwarding on VirtualBox (the NAT delivers to the guest's NAT address), but some providers need it on 0.0.0.0. Frameworks often default to localhost; start them with --host 0.0.0.0.
  2. Is the guest firewall (ufw) blocking the port?
  3. Is the host port really free? Try netstat -ano (Windows) or lsof -i :8080 (macOS/Linux).
  4. Does vagrant port show what you expect?

A frequent trap: a Node, Python or Rails dev server started with its default 127.0.0.1 binding works inside the VM but not through some forwarding setups. Binding to 0.0.0.0 inside the guest is harmless because the VM is not exposed unless you forward the port.

Rule resolution model

The stand-in below mimics how Vagrant resolves forwarded ports: it reads a list of rules, detects host-port collisions, and applies auto_correct using the usable port range. It is Ruby, not Vagrant, but it shows why the final ports may differ from the Vagrantfile.

Ruby Port collision and auto_correct (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.

Alternatives to forwarding

Forwarded ports are the quickest option and work on every provider and network setup, even behind strict corporate networks. Their limits: one port at a time, a different port for each guest, no real hostname. When you need many services, hostnames or reaching the VM from other machines, use a private or public network instead, which gives the VM its own IP address.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does config.vm.network "forwarded_port", guest: 80, host: 8080 do?

    Host port 8080 is mapped to guest port 80: host to guest.
  2. 2. Why set host_ip: "127.0.0.1"?

    Without it the port listens on all host interfaces and can be reached from your network.
  3. 3. What happens when auto_correct: true and the host port is busy?

    Vagrant chooses a free port from the usable range and reports it with vagrant port.
  4. 4. Why does host: 80 often fail for normal users on Linux and macOS?

    Privileged ports below 1024 need root on the host; use a port like 8080 instead.

Summary

  • forwarded_port maps a host port to a guest port; vagrant port lists the real rules.
  • Bind to 127.0.0.1 with host_ip unless you intend to share the service on your network.
  • Collisions stop vagrant up; auto_correct: true picks another port automatically.
  • Ports below 1024 need privileges on Linux and macOS.
  • For many services or real hostnames, use a private or public network.

Next: Private and Public Networks