Port Forwarding

Port forwarding maps ports on the guest VM to localhost on the host, making services running inside the VM accessible from the host Mac.

Configuring Port Forwards

In the GUI

There are two ways to configure port forwards:

• Edit VM Settings — right-click a VM, choose “Edit Settings”, and add port forwards in the Port Forwards section. These are saved to config.json and persist across restarts.
• Runtime editor — click the network icon in the VM toolbar to add or remove forwards while the VM is running.

In config.json

{
  "portForwards": [
    { "hostPort": 8080, "guestPort": 80 },
    { "hostPort": 2222, "guestPort": 22 }
  ]
}

Auto Port Detection

GhostVM automatically detects listening TCP ports inside the guest (reported by GhostTools) and creates port forwards on the fly. No manual configuration is needed for most workflows.

Process Names

Each auto-detected port shows the name of the process that opened it — for example node, python, or postgres. This makes it easy to tell which service is behind each port at a glance.

Notification Popup

When a new port is detected, a lightweight notification appears so you know a service just started listening. No action is required — the forward is already active.

Management Panel

Click the network icon in the VM toolbar to open the management panel. From here you can:

• Block or unblock individual auto-detected ports
• Copy the localhost URL for any forward
• Manually add or remove static port forwards

Host Port Fallback

If the desired host port is already in use, GhostVM tries port+1, port+2, and so on until it finds an available port. The actual host port is shown in the management panel.

How it Works

Port forwarding is implemented using NIO (Swift NIO). For each forward, GhostVM:

1. Binds a TCP listener on localhost:{hostPort}
2. When a connection arrives, opens a vsock connection to the guest on the guest port
3. Relays data bidirectionally between the TCP socket and the vsock connection

Common Use Cases