qovery port-forward

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. Port-forwarding requires the Port-forward permission on the service’s environment type. See Shell and Port-forward permissions.

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 Rejected

If each connection is rejected with Port-forward connection rejected: check your permissions or run 'qovery auth', run qovery auth first, as an expired session gives the same error. If the rejection persists, your role does not have the Port-forward permission on this environment type. Ask an organization admin to grant it. See Shell and Port-forward permissions.

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

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

Getting Started

Commands

Troubleshooting

qovery port-forward

Overview

Command

Usage

Options

Examples

Forward a Single Port

Forward Multiple Ports

Access PostgreSQL Database

Access Application API Locally

Use Cases

Tips

Troubleshooting

Port Already in Use

Connection Rejected

Connection Drops

​Overview

​Command

​Usage

​Options

​Examples

​Forward a Single Port

​Forward Multiple Ports

​Access PostgreSQL Database

​Access Application API Locally

​Use Cases

​Tips

​Troubleshooting

​Port Already in Use

​Connection Rejected

​Connection Drops

​Related Commands

Overview

Command

Usage

Options

Examples

Forward a Single Port

Forward Multiple Ports

Access PostgreSQL Database

Access Application API Locally

Use Cases

Tips

Troubleshooting

Port Already in Use

Connection Rejected

Connection Drops

Related Commands