# What is SSH port forwarding?

SSH port forwarding sends a TCP connection through an SSH session. A port on
one machine then responds as if it were a port on another machine.

**`runtime sandboxes port-forward <id> 5432` makes `localhost:5432` on your
machine connect to the database in a Runtime sandbox. The traffic goes through
the API, and no port is opened to the internet.** Any TCP port works, not only
HTTP. That includes Redis, a debugger, and a dev server that uses WebSockets
([forward ports](/docs/editors#forward-ports)).

## Local and remote forwarding

RFC 4254, the SSH connection protocol, defines both directions as channel
types:

| Direction | Channel                                 | What it does                                                      |
| --------- | --------------------------------------- | ----------------------------------------------------------------- |
| Local     | `direct-tcpip`                          | A port on your machine reaches a host and port the server can see |
| Remote    | `tcpip-forward`, then `forwarded-tcpip` | A port on the server reaches back to your machine                 |

With OpenSSH, `ssh -L 5432:localhost:5432 server` sets up local forwarding.
`ssh -R 8080:localhost:3000 server` sets up remote forwarding.

## When to forward, and when to publish

A forward is private. Only the machine that runs it can use the port. It stays
open until you press Ctrl-C. To let others reach a service, publish it instead.

| You want                               | On Runtime                                                                 |
| -------------------------------------- | -------------------------------------------------------------------------- |
| Your own tools on a sandbox's database | `runtime sandboxes port-forward`                                           |
| A link to a web app for someone else   | A [preview URL](/glossary/preview-url), private by default                 |
| A raw TCP port anyone can reach        | A TCP port, on a paid account ([open a TCP port](/how-to/open-a-tcp-port)) |
| Private traffic with your own servers  | A WireGuard tunnel, $5 a 30-day month                        |

## Keep the server running

A forward needs a process that listens on the port. Start the server with
`runtime sandboxes spawn <id> -- <command>` so that it keeps running. A process
started by `exec` ends when its command ends. The forward reports an error when
nothing listens on the port.

## Related

- [How to port-forward a database from a sandbox](/how-to/port-forward-a-database)
- [What is SSH?](/glossary/ssh)
- [What is a preview URL?](/glossary/preview-url)
- [How to open a TCP port](/how-to/open-a-tcp-port)

## Sources

Checked 25 October 2026.

- [RFC 4254, The Secure Shell (SSH) Connection Protocol](https://www.rfc-editor.org/rfc/rfc4254)
- [Runtime SSH and editors](/docs/editors#forward-ports)