qovery port-forward

Port forwarding command

Overview

Forward a local port to a service container port. This allows you to access services running in your Qovery environment from your local machine.

Command

qovery port-forward

The command requires at least one --port flag specifying the port mapping in local_port:remote_port format.

Usage

qovery port-forward [flags]

Options

Flag	Short	Required	Description
--port	-p	Yes	Port to forward. Format: local_port:remote_port (e.g. 8080:80). Can be specified multiple times.
--pod		No	Pod name where to forward traffic
--help			Show help

Examples

Forward a Single Port

# Forward local port 8080 to remote port 80
qovery port-forward --pod "my-app-7d8f9c5b6-xyz12" --port 8080:80

Forward Multiple Ports

# Forward multiple ports at once
qovery port-forward --pod "my-app-7d8f9c5b6-xyz12" --port 8080:80 --port 5432:5432

Access PostgreSQL Database

# Forward PostgreSQL port
qovery port-forward --pod "my-db-5f7c9b4d2-abc34" --port 5432:5432

# In another terminal, connect with psql
psql -h localhost -p 5432 -U myuser -d mydatabase

Access Application API Locally

# Forward application port
qovery port-forward --pod "my-app-7d8f9c5b6-xyz12" --port 8080:8080

# Access API on http://localhost:8080
curl http://localhost:8080/api/health

Use Cases

Database Access

Forward database ports to run queries, migrations, or admin tools locally without exposing databases publicly.

# PostgreSQL
qovery port-forward --pod "my-db-5f7c9b4d2-abc34" --port 5432:5432

# MySQL
qovery port-forward --pod "my-db-5f7c9b4d2-abc34" --port 3306:3306

# MongoDB
qovery port-forward --pod "my-db-5f7c9b4d2-abc34" --port 27017:27017

# Redis
qovery port-forward --pod "my-db-5f7c9b4d2-abc34" --port 6379:6379

Debugging Applications

Access application debug ports or admin interfaces that aren’t exposed publicly.

# Access admin panel
qovery port-forward --pod "my-app-7d8f9c5b6-xyz12" --port 8080:8080

# Access debug endpoint
qovery port-forward --pod "my-app-7d8f9c5b6-xyz12" --port 9090:9090

Local Development

Connect your local development environment to remote services (databases, APIs, microservices).

# Forward remote database to local app
qovery port-forward --pod "my-db-5f7c9b4d2-abc34" --port 5432:5432

# Run local app connecting to remote DB
DATABASE_URL=postgresql://localhost:5432/mydb npm run dev

API Testing

Test APIs or services that aren’t publicly accessible.

# Forward internal API
qovery port-forward --pod "my-app-7d8f9c5b6-xyz12" --port 8080:8080

# Test with curl
curl http://localhost:8080/api/test

Tips

Port forwarding creates a secure tunnel through Kubernetes. The connection is encrypted and authenticated.

Keep the port-forward command running in a terminal window. The tunnel closes when you stop the command (Ctrl+C).

Port forwarding is for development and debugging. For production access, use proper ingress, load balancers, or VPN solutions.

The connection will drop if the pod restarts. You’ll need to restart the port-forward command.

Troubleshooting

Port Already in Use

If the local port is already in use:

# Check what's using the port
lsof -i :8080

# Use a different local port
qovery port-forward --pod "my-app-7d8f9c5b6-xyz12" --port 8081:8080

Connection Drops

If the connection drops frequently:

# Use a specific pod instead of letting Kubernetes choose
qovery port-forward --pod "my-app-pod-name" --port 8080:8080

Related Commands

• qovery shell - Execute commands in container
• qovery log - View service logs
• qovery status - Check service status