Tunnels and forwards

Ports on your instances, and anything they can reach, on your Mac's loopback.

Updated

New Tunnel… (⌘T), or Tunnel to Port… on an instance, forwards a port of that instance to 127.0.0.1 on your Mac. Pick a preset (SSH, RDP, PostgreSQL, MySQL, SQL Server, Redis, HTTP, HTTPS) or a custom port. The local port stays the same between runs. A port below 1024 is offered 8000 higher (HTTP on 8080), and Ostgate never offers a port that browsers refuse, such as 6000; if you type one, the sheet says so. Start automatically when this account opens brings the tunnel back with its account.

Forward a VM port to 127.0.0.1 over IAP with the PostgreSQL preset

On an instance with more than one network interface, Interface picks the one the tunnel goes to; the default is nic0.

The Tunnel to Port sheet for example-waf, a VM with two network interfaces: Interface is set to nic1 · dmz · 10.0.9.17, the HTTP preset is selected, and the sheet reads Listens on 127.0.0.1:8080 → 10.0.9.17:80.
Tunnel to Port on a second network interface

Under Options, Access decides which programs on your Mac may use the tunnel:

  • Ostgate only: the default for SSH, RDP and custom ports.
  • My processes: any app running as your macOS user, such as a database client or a browser. The default for database and web presets.
  • Any local process…: every program on the Mac, only after you confirm a shared tunnel.

Tunnels are listed under Connections and in the menu bar. They keep running when you close the window, and reconnect by themselves after a network drop. Copy Command gives you the matching client command line.

The menu bar icon counts live and failed connections. Its panel lists every account's tunnels and forward profiles, failed ones first with the reason, then open sessions and Quick Connect.

Ostgate's menu bar icon with badges 6 and 1, and its panel open below: Acme's failed tunnel win-build-rdp reads Failed · VM port 3389 not reachable, above the tunnels pg-primary, win-example-rdp and web-1-http and the forward profile acme-internal; Northwind's tunnel warehouse-ui and forward profile northwind-etl; three sessions; Quick Connect to pg-primary, win-example and etl-worker-1; Quit Ostgate.
Menu bar panel: live and failed counts, Copy, Stop, Diagnose and Retry in the rows, open sessions and Quick Connect
  • Forward profiles (Connections › Forwards › New Forward Profile…) reach anything a chosen VM can see, such as an internal load balancer or a private database, several ports at once over one SSH session. Optionally they manage /etc/hosts aliases while running, after macOS asks for an administrator's password. Ostgate first shows a panel that says why it needs the password, and Cancel there skips the macOS dialog. With the port helper installed, an administrator's aliases need no password, except names such as googleapis.com or apple.com; edits in Local › Hosts still ask. An alias that is not written shows on the profile's row with Retry.
  • A forward can listen on a port below 1024, such as 443 or 22, once it has a host alias and Manage /etc/hosts aliases while running is on. It listens on its alias's own address, 127.0.0.2 to 127.0.0.254, so a URL or an SSH clone URL needs no port number. The Ostgate port helper binds the port: allow it once in System Settings › General › Login Items. While it is installed, it also writes the forwards' aliases to /etc/hosts without the password prompt when your macOS user is an administrator. Ostgate removes its addresses and aliases on Stop, on Quit, and after a crash at the next launch. The guide Forward ports 443 and 22 to your Mac covers the setup step by step.
  • Cloud SQL: Open Tunnel… on an instance with a private IP, or with a Private Service Connect endpoint, reaches it through one of your running Linux VMs. Via bastion lists the VMs on the network of the instance or its endpoint first, by project, then Other networks, which can reach it only through peering or a VPN. The list reloads each time the sheet opens, so a VM started in the Cloud console appears in it.
  • Cloud Run: Open in Browser opens an internal-only service through a local proxy. Services that require IAM authentication cannot be opened yet.
  • Local › Local Ports lists every listener on your Mac's loopback and stops stuck ones; Local › Hosts edits /etc/hosts.
Ostgate's Local view: Local Ports lists each loopback listener with its port, process, owner and account, naming Ostgate's own tunnels and forwards, the SSH tabs web-1 and etl-worker-1, the RDP tab win-example, the bastion link of forward acme-internal and the inner port of the orders-api proxy, next to node and redis-server owned by you; below it, Hosts lists /etc/hosts with reporting-db.local managed by Acme's Forward “acme-internal”.
Local Ports and Hosts

When a tunnel's or forward's access setting turns a program away, its row says so, for example “Refused nc — only Ostgate may connect”. Change Access…, on that notice or in a tunnel's menu, switches the level in place. For a forward profile it opens the profile's editor, and saving restarts a running profile with the new access.

Ostgate's Connections view: the pg-primary tunnel, which only Ostgate may use, reads Refused psql ×2 — only Ostgate may connect, with a Change Access… button, above three more tunnels and two forward profiles.
A refused connection and Change Access…