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.
On an instance with more than one network interface,
Interface picks the one the tunnel goes to; the default is nic0.
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.
- 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/hostsaliases 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 asgoogleapis.comorapple.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.2to127.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/hostswithout 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.
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.