# How to port-forward a database from a sandbox to your machine

Run `runtime sandbox port-forward <id> 5432`; `localhost:5432` on your machine then reaches Postgres inside the sandbox.

**On Runtime a port forward exposes nothing publicly: it runs through Runtime's
API with your key, and the sandbox never opens a port to the internet.** Any
TCP port works, not only HTTP, so Postgres, MySQL, Redis, a debugger or a dev
server with WebSockets all come to your laptop the same way, and a paused
sandbox is woken by the connection. The database runs in a Firecracker microVM
that costs $0.03125 an hour at 2 vCPU and 4 GiB while it waits for queries
([pricing](/docs/pricing)).

## Forward Postgres

Install and start the database in the sandbox with `spawn`, which keeps it
running, then forward its port:

```bash no-run
runtime sandbox exec <id> -- sudo apt-get install -y postgresql
runtime sandbox spawn <id> -- sudo -u postgres /usr/lib/postgresql/16/bin/postgres -D /var/lib/postgresql/16/main -c config_file=/etc/postgresql/16/main/postgresql.conf
runtime sandbox port-forward <id> 5432              # localhost:5432 here is 5432 in the sandbox
psql -h 127.0.0.1 -p 5432 -U postgres
```

Those are the paths of Ubuntu 24.04's PostgreSQL 16 package. A process
started by `exec` ends with its command, `nohup … &` included, which
is why the server goes through `spawn`. The server may listen on `127.0.0.1`,
`::1` or every address inside the sandbox. `port-forward` listens on
`127.0.0.1` on your side unless you pass `--address`, runs until Ctrl-C, and
says so when nothing listens on the port.

## Several ports, or a different local port

```bash no-run
runtime sandbox port-forward <id> 3000 15432:5432   # local:remote; 3000 as 3000, 5432 as 15432
```

A local database already on 5432 keeps its port; the sandbox's arrives at 15432.

## From code

The SDKs open the same forward from a test or a script. `localPort: 0` picks
a free port:

```ts check
import { Sandbox } from "withruntime";

await using sbx = await Sandbox.create();
await sbx.exec("sudo apt-get install -y redis-server", { check: true, timeoutMs: 300_000 });
await sbx.spawn("redis-server --port 6379");
const forward = await sbx.forwardPort(6379, { localPort: 0 });
console.log(`redis://127.0.0.1:${forward.localPort}`);
await forward.close();
```

```python check
from withruntime import Sandbox

with Sandbox.create() as sbx:
    sbx.exec("sudo apt-get install -y redis-server", check=True, timeout_ms=300_000)
    sbx.spawn("redis-server --port 6379")
    with sbx.forward_port(6379, local_port=0) as forward:
        print(f"redis://127.0.0.1:{forward.local_port}")
```

In JavaScript, `sbx.tunnel()` opens one connection at a time instead:
`tunnel.connect(5432)` gives a stream to the port, for a driver that accepts
one.

## Limits

| Limit                                | Value                                                       |
| ------------------------------------ | ----------------------------------------------------------- |
| Ports                                | Any TCP port except 10800, the sandbox's own outbound proxy |
| Connections through one forward      | 64 at once                                                  |
| SSH logins and forwards open at once | 16 per organization                                         |
| Longest forward                      | 24 hours; open it again to go on                            |
| Local listen address                 | `127.0.0.1` unless `--address` says otherwise               |

## Mistakes and how Runtime handles them

- **"Nothing listens on the port."** The server was started with `exec` and
  ended, or has not finished starting. Start it with `spawn` and check it with
  `runtime sandbox ps <id>` and `runtime sandbox logs <id> <pid>`.
- **The forward drops when the lease ends.** An open connection does not keep
  a sandbox running. Extend the lease (`runtime sandbox extend <id> 3600`) for
  a long session.
- **A connection pool larger than 64.** One forward carries at most 64
  connections at once; size the pool below that.
- **Sharing the forward with teammates.** `--address` can listen on another
  interface, but each teammate can run their own forward with their own key
  instead, and nothing is exposed.

## Forward, public port or tunnel?

A forward is for you, from your own machine, for as long as you work. When
clients elsewhere must connect, a paid account can
[open a public TCP port](/how-to/open-a-tcp-port). When your own servers need
steady private access to many sandboxes, use a
[WireGuard tunnel](/how-to/connect-a-wireguard-tunnel). The same forward serves
a published Docker port: see [run Docker in a sandbox](/how-to/run-docker-in-a-sandbox).

## Related

- [Forward ports](/docs/editors#forward-ports) in the SSH and editors guide.
- [SSH into a sandbox](/how-to/ssh-into-a-sandbox).
- [The sandbox environment](/docs/sandbox-environment).

## Start

```bash no-run
npx withruntime sandbox run --trial --keep -- true
```

New accounts get 50 free sandbox hours, no card.

Facts on this page were checked on 25 September 2026.