Guides

Raw ports

Forward non-HTTP ports (ssh, DNS, WireGuard) to an app unchanged.

The proxy routes an app's hostnames to httpPort. An app can also listen on other ports, TCP or UDP. Traffic to those ports is forwarded unchanged, like a firewall rule:

"config": {
  "httpPort": 3000,
  "ports": [
    { "name": "ssh", "guestPort": 22 },
    { "name": "dns", "guestPort": 53 }
  ]
}

Host configuration

The host must have a [proxy.raw] section to bind raw ports:

[proxy.raw]
listen_address = "10.0.5.18"
max_ports_per_guest = 2
  • max_ports_per_guest is how many raw ports an app may declare: 1 to 7, the ports a slot reserves after its HTTP port. An app that declares more is reported failed, naming the key.
  • listen_address must be a private address: one a relay reaches the host on, not a public one. A raw port carries no hostname to route on, so it is reached at <listen_address>:<host port>. The host port is the app's hostPort in reported.json plus the port's 1-based position in ports. In the example above, ssh is hostPort + 1 and dns is hostPort + 2.

Do not publish raw ports from the host

If an app gave its users the host's address, they would reach every app's raw ports. Publish them from a separate relay machine.

Waking

If the app is asleep, the first packet on any raw port wakes it. A TCP connection is accepted and held, then forwarded once the guest accepts it, so the client sees a delay rather than a refused connection. A UDP datagram is queued and delivered after the wake.

On this page