> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Port forwarding

> Expose a raw TCP or UDP port on a machine — for databases, game servers, and anything that isn't HTTP.

## Raw ports vs HTTPS proxies

[Proxies](/how-it-works/proxies) terminate TLS and route **HTTP** by domain — perfect for web apps and APIs. But a Postgres database, an SSH daemon, a game server, or any other protocol that isn't HTTP needs a raw transport-layer port instead.

`expose` opens a **raw TCP or UDP port** on the machine's public proxy and forwards it straight to a port inside the VM. No TLS termination, no HTTP parsing — just packets.

```
myapp.boxd.sh:48211  ->  your machine, port 5432 (Postgres)
```

The public port is allocated for you from the **40000–60000** range. The endpoint is the machine's existing DNS name (`name.boxd.sh`, which resolves to the proxy IP) on that allocated port.

## Expose a port

```bash theme={"theme":"github-dark"}
boxd machine proxy add --vm myapp --port 5432 --raw
```

```
exposed myapp.boxd.sh:48211 -> 5432 (tcp)
```

Anything listening on `5432` inside the VM is now reachable at `myapp.boxd.sh:48211`. For example, a Postgres client:

```bash theme={"theme":"github-dark"}
psql -h myapp.boxd.sh -p 48211 -U postgres
```

## Protocols

A forward is TCP by default. Use `--udp` for UDP, or pass both flags to serve TCP **and** UDP on the same allocated public port:

```bash theme={"theme":"github-dark"}
boxd machine proxy add --vm myapp --port 5432 --raw             # TCP (default)
boxd machine proxy add --vm myapp --port 9999 --raw --udp       # UDP
boxd machine proxy add --vm myapp --port 7777 --raw --tcp --udp # both, one public port
```

Re-running `expose` for a port you've already exposed keeps the same public port and just updates the protocol set.

## List and remove

```bash theme={"theme":"github-dark"}
boxd machine proxy list                   # all your exposed ports
boxd machine proxy remove 5432 --vm myapp # remove a forward, free the public port
```

```
myapp.boxd.sh:48211 -> 5432 (tcp)
myapp.boxd.sh:51005 -> 7777 (udp + tcp)
```

## Limits

* **Up to 3 forwarded ports per VM.** Each allocated public port serves one inside-VM port (in one or both protocols). Remove one before exposing a fourth.
* **Owner-only.** Only the machine's owner can expose, list, or remove its forwards.
* Forwards persist across reboots and are removed automatically when the VM is destroyed.

<Note>
  `expose` is for non-HTTP traffic. If you're serving a website or HTTP API, use an [HTTPS proxy](/how-it-works/proxies) instead — you get TLS and a clean `https://name.boxd.sh` URL for free.
</Note>

## Surfaces

`expose` works the same from every surface:

```bash theme={"theme":"github-dark"}
boxd machine proxy add --vm myapp --port 5432 --raw # laptop CLI
boxd machine expose 5432                             # in-VM CLI (current VM); or `boxd machine expose other 5432`
```

See the [CLI reference](/reference/external-cli#exposing-raw-tcp-udp-ports) for the full flag list.