Port forwarding
hq forward makes a port on the AI Team Cloud Computer reachable on this computer, for a dev server, an API or a database.
Forward a port
- Start the server on the AI Team Cloud Computer
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.
- Forward it
hq forward 3000Forwarding http://localhost:3000 -> Backend :3000 (Ctrl-C to stop) - Use it, then stop
Open
http://localhost:3000in your browser, or point any tool at it. PressCtrl-Cin 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--teamis optional when exactly one of your teams lets you forward ports.- The local port listens on
127.0.0.1only, so other computers on your network cannot reach it. - A sleeping AI Team Cloud Computer 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 AI Team Cloud Computer uses itself.
- On the AI Team Cloud Computer, 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 AI Team Cloud Computer 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.