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

Forward Postgres

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

Terminalruntime sandbox exec <id> -- sudo apt-get install -y postgresqlruntime 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.confruntime sandbox port-forward <id> 5432              # localhost:5432 here is 5432 in the sandboxpsql -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

Terminalruntime 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:

TypeScriptimport { 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();

Pythonfrom withruntime import Sandboxwith 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

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. When your own servers need steady private access to many sandboxes, use a WireGuard tunnel. The same forward serves a published Docker port: see run Docker in a sandbox.

Related

• Forward ports in the SSH and editors guide.
• SSH into a sandbox.
• The sandbox environment.

Start

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