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

# Port Forward to Workloads

> Access workload ports locally by forwarding traffic through a secure tunnel.

The `cpln port-forward` command creates a secure tunnel between your local machine and a workload, allowing you to access ports without exposing them publicly. Similar to `kubectl port-forward`, this enables local access to databases, internal services, and debugging endpoints.

## When to use this

<CardGroup cols={2}>
  <Card title="Access databases" icon="database">
    Connect to PostgreSQL, MySQL, Redis, or other databases running in workloads
  </Card>

  <Card title="Debug internal services" icon="bug">
    Access admin panels, metrics endpoints, or debug ports locally
  </Card>

  <Card title="Local development" icon="code">
    Test against live services without deploying your code
  </Card>

  <Card title="Private service access" icon="key">
    Interact with services that aren't publicly exposed
  </Card>
</CardGroup>

## Prerequisites

<AccordionGroup>
  <Accordion title="CLI installed">
    Install the Control Plane CLI. See [Installation](/cli-reference/installation).
  </Accordion>

  <Accordion title="Running workload">
    You need a running [workload](/reference/workload) in at least one location. See the [Create a Workload](/guides/create-workload) guide.
  </Accordion>

  <Accordion title="Required permissions">
    You need `connect` permission on the workload. See [Workload Permissions](/reference/workload#permissions).
  </Accordion>
</AccordionGroup>

## Basic usage

```bash theme={null}
cpln port-forward <workload> <local-port>:<remote-port>
```

This forwards traffic from `localhost:<local-port>` to `<remote-port>` on the workload.

<Tip>
  You can get a ready-to-use port-forward command from the Console. Navigate to your workload, click **Connect** in the left pane, and copy the port-forward command which includes the location and port mapping (e.g., `80:80`).
</Tip>

## Options

| Option       | Description                                                          |
| ------------ | -------------------------------------------------------------------- |
| `--address`  | Local addresses to listen on, comma-separated (default: `localhost`) |
| `--location` | Target location (defaults to first available in GVC)                 |
| `--replica`  | Target a specific replica (defaults to any available)                |

## Port format options

<Tabs>
  <Tab title="Different ports">
    Map a different local port to the remote port:

    ```bash theme={null}
    cpln port-forward my-db 5433:5432
    ```

    Access the database at `localhost:5433`.
  </Tab>

  <Tab title="Same port">
    Use the same port locally and remotely:

    ```bash theme={null}
    cpln port-forward my-db 5432
    ```

    This is shorthand for `5432:5432`.
  </Tab>

  <Tab title="Ephemeral port">
    Let the system assign a local port:

    ```bash theme={null}
    cpln port-forward my-db :5432
    ```

    The CLI outputs the assigned port. Useful when the port may be in use.
  </Tab>
</Tabs>

## Forward multiple ports

Forward several ports in one command:

```bash theme={null}
cpln port-forward my-app 8080:80 8443:443 9090:9090
```

Access the app at:

* `localhost:8080` (HTTP)
* `localhost:8443` (HTTPS)
* `localhost:9090` (metrics)

## Listen on multiple addresses

Expose the forwarded port on multiple network interfaces:

```bash theme={null}
cpln port-forward my-db 5432:5432 --address 127.0.0.1,192.168.1.10
```

This allows other machines on your LAN to connect through `192.168.1.10:5432`.

<Warning>
  Listening on non-localhost addresses exposes the port to your network. Use with caution.
</Warning>

## Target specific locations

Forward to a workload in a specific location:

```bash theme={null}
cpln port-forward my-db 5432:5432 --location aws-eu-central-1
```

<Tip>
  Choosing a location closer to you reduces latency.
</Tip>

## Common workflows

### Connect to PostgreSQL

```bash theme={null}
# Start port forward
cpln port-forward postgres-db 5432:5432 --gvc production

# In another terminal, connect with psql
psql -h localhost -p 5432 -U postgres
```

### Access Redis

```bash theme={null}
cpln port-forward redis-cache 6379:6379

# Connect with redis-cli
redis-cli -h localhost -p 6379
```

### Debug a web service

```bash theme={null}
cpln port-forward my-api 8080:80 9090:9090

# Access the API
curl http://localhost:8080/health

# Access metrics
curl http://localhost:9090/metrics
```

### Access admin panels

```bash theme={null}
# Forward to admin port
cpln port-forward my-app 9000:9000

# Open in browser
open http://localhost:9000/admin
```

## Port forwarding to unexposed ports

You can forward to any port on the workload, even if no container is listening on that port.

<Info>
  This is useful for debugging or accessing services that bind to ports dynamically.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Port already in use">
    The local port is occupied. Use a different port or an ephemeral port:

    ```bash theme={null}
    cpln port-forward my-db :5432
    ```
  </Accordion>

  <Accordion title="Connection refused">
    The workload may not be listening on that port. Verify the container port:

    ```bash theme={null}
    cpln workload get my-db --output yaml
    ```

    Check the `ports` section in the container spec.
  </Accordion>

  <Accordion title="No replicas found">
    The workload may not be running in the specified location:

    ```bash theme={null}
    cpln workload replica get my-db
    ```

    Try a different location or wait for replicas to start.
  </Accordion>

  <Accordion title="Permission denied">
    You need `connect` permission on the workload. Check your policies.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Connect to Workloads" href="/guides/cli/workload/connect" icon="plug">
    Interactive shell access
  </Card>

  <Card title="Execute Commands" href="/guides/cli/workload/exec" icon="terminal">
    Run commands in containers
  </Card>

  <Card title="Copy Files" href="/guides/cli/cpln-cp" icon="copy">
    Transfer files to/from workloads
  </Card>

  <Card title="Command Reference" href="/cli-reference/commands/port-forward" icon="book">
    Full port-forward command reference
  </Card>
</CardGroup>