Port forwarding

Forward a port

1. Start the server on the team machine

   In an HQ session, start whatever listens on the port, for example a dev server on port 3000. It must use a port from 1024 to 65535.

2. Forward it

   hq forward 3000

   Forwarding http://localhost:3000 -> Backend :3000   (Ctrl-C to stop)

3. Use it, then stop

   Open http://localhost:3000 in your browser, or point any tool at it. Press Ctrl-C in the terminal to stop forwarding.

Options

# use a different port on this computer
hq forward 5173 --local 8080

# pick the team when more than one lets you forward
hq forward 3000 --team hq-3f9a1c2e

• --team is optional when exactly one of your teams lets you forward ports.
• The local port listens on 127.0.0.1 only, so other computers on your network cannot reach it.
• A sleeping team machine is woken when the forward starts.
• Every connection your browser or tool opens gets its own tunnel through HQ; the forward stays open until you stop it or your access ends.
• HQ refuses some ports: the Docker API (2375 and 2376), the Node debugger (9229 and 9230), and ports the team machine uses itself.
• On the team machine, a forward reaches whatever listens on that port, including another member's dev server.

Forwarding or Preview?

Preview, in the HQ web app, opens a port in your browser from HQ with nothing to install. It finds the ports your team machine is serving on its own, including Docker containers and servers that never print a URL. Use hq forward when a tool on this computer needs the port itself on localhost: a database or API client, local tests, or your own browser profile and extensions. In VS Code, the extension forwards ports too: see Ports.

Related