> ## Documentation Index
> Fetch the complete documentation index at: https://www.qovery.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
qovery port-forward
```

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

## Usage

```bash theme={null}
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

```bash theme={null}
# Forward local port 8080 to remote port 80
qovery port-forward --pod "my-app-7d8f9c5b6-xyz12" --port 8080:80
```

### Forward Multiple Ports

```bash theme={null}
# Forward multiple ports at once
qovery port-forward --pod "my-app-7d8f9c5b6-xyz12" --port 8080:80 --port 5432:5432
```

### Access PostgreSQL Database

```bash theme={null}
# 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

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Database Access">
    Forward database ports to run queries, migrations, or admin tools locally without exposing databases publicly.

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Debugging Applications">
    Access application debug ports or admin interfaces that aren't exposed publicly.

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Local Development">
    Connect your local development environment to remote services (databases, APIs, microservices).

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="API Testing">
    Test APIs or services that aren't publicly accessible.

    ```bash theme={null}
    # Forward internal API
    qovery port-forward --pod "my-app-7d8f9c5b6-xyz12" --port 8080:8080

    # Test with curl
    curl http://localhost:8080/api/test
    ```
  </Accordion>
</AccordionGroup>

## Tips

<Tip>
  Port forwarding creates a secure tunnel through Kubernetes. The connection is encrypted and authenticated.
</Tip>

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

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

<Warning>
  The connection will drop if the pod restarts. You'll need to restart the port-forward command.
</Warning>

## Troubleshooting

### Port Already in Use

If the local port is already in use:

```bash theme={null}
# 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:

```bash theme={null}
# Use a specific pod instead of letting Kubernetes choose
qovery port-forward --pod "my-app-pod-name" --port 8080:8080
```

## Related Commands

* [`qovery shell`](/cli/commands/shell) - Execute commands in container
* [`qovery log`](/cli/commands/log) - View service logs
* [`qovery status`](/cli/commands/status) - Check service status