Port Forwarding & SSH

macpine makes it easy to expose network services running inside your VM to your macOS host. This is essential for web development, database connections, and accessing your VM via SSH.

SSH Access

Every macpine instance has an SSH server running. To access it, you must forward a port from your host to port 22 inside the VM.

  • The -s, --ssh flag on alpine launch controls this.
  • It defaults to a random high port if not specified, but you can choose a specific one.
# Forward host port 2022 to the instance's SSH port (22)
alpine launch -s 2022 --name my-ssh-vm

# Connect to the instance
alpine ssh my-ssh-vm
# Alternatively, use a standard ssh client:
# ssh root@localhost -p 2022  (password: root)

General Port Forwarding

For services other than SSH (like web servers or databases), use the -p, --port flag.

Port Forwarding Syntax

The port forwarding string is a comma-separated list of mappings. Each mapping follows this format:

<host_port>:<guest_port>[u]
  • <host_port>: The port on your macOS machine.
  • <guest_port>: The port inside the Alpine VM.
  • If :guest_port is omitted, it's assumed to be the same as host_port.
  • Append u for UDP protocol. The default is TCP.

Examples

Example 1: Forward a web server port

Forward host port 8080 to guest port 80 in the VM.

alpine launch -p 8080:80 --name web-server
Now, if you run a web server on port 80 inside the web-server VM, you can access it at http://localhost:8080 in your Mac's browser.

Example 2: Multiple and complex forwarding

  • Forward host port 8888 to guest port 8888 (TCP).
  • Forward host port 5433 to guest port 5432 (TCP, for PostgreSQL).
  • Forward host port 9000 to guest port 9000 (UDP).
alpine launch -s 2222 -p 8888,5433:5432,9000u --name complex-vm

Network Modes

SLIRP (Default)

By default, macpine uses QEMU's User-mode networking (SLIRP). This mode creates a private network for the VM and doesn't require administrator privileges. All network access must be configured via explicit port forwarding as described above.

VMNet-Shared

For more advanced use cases, you can use Apple's native vmnet-shared framework. This gives the VM its own IP address on your local network, making all its ports accessible without individual forwarding. This mode requires running alpine launch with sudo.

sudo alpine launch --shared --name vmnet-instance

# Find the instance's IP address
alpine info vmnet-instance
# Name: vmnet-instance
# IP: 192.168.1.123  <-- Use this IP to connect
# ...