# 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 [#forward-a-port]

<Steps>
  <Step title="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.
  </Step>

  <Step title="Forward it">
    ```bash
    hq forward 3000
    ```

    ```text
    Forwarding http://localhost:3000 -> Backend :3000   (Ctrl-C to stop)
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Options [#options]

```bash
# 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? [#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](/docs/vscode/ports/).

## Related [#related]

<Cards>
  <Card title="Attach to a session" href="/docs/cli/attach/">
    Start a server from your terminal, in an HQ session.
  </Card>

  <Card title="CLI reference" href="/docs/cli/reference/#hq-forward">
    Every flag and exit code of `hq forward`.
  </Card>

  <Card title="Troubleshooting" href="/docs/cli/troubleshooting/">
    Ports, teams and refused forwards.
  </Card>
</Cards>
