AI Workforce OneHQDocs

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

  1. 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.

  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 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.