Port Forward to Workloads

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

Access databases

Connect to PostgreSQL, MySQL, Redis, or other databases running in workloads

Debug internal services

Access admin panels, metrics endpoints, or debug ports locally

Local development

Test against live services without deploying your code

Private service access

Interact with services that aren’t publicly exposed

Prerequisites

CLI installed

Install the Control Plane CLI. See Installation.

Running workload

You need a running workload in at least one location. See the Create a Workload guide.

Required permissions

You need connect permission on the workload. See Workload Permissions.

Basic usage

cpln port-forward <workload> <local-port>:<remote-port>

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

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

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

Different ports
Same port
Ephemeral port

Map a different local port to the remote port:

cpln port-forward my-db 5433:5432

Access the database at localhost:5433.

Use the same port locally and remotely:

cpln port-forward my-db 5432

This is shorthand for 5432:5432.

Let the system assign a local port:

cpln port-forward my-db :5432

The CLI outputs the assigned port. Useful when the port may be in use.

Forward multiple ports

Forward several ports in one command:

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:

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.

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

Target specific locations

Forward to a workload in a specific location:

cpln port-forward my-db 5432:5432 --location aws-eu-central-1

Choosing a location closer to you reduces latency.

Common workflows

Connect to PostgreSQL

# 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

cpln port-forward redis-cache 6379:6379

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

Debug a web service

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

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

This is useful for debugging or accessing services that bind to ports dynamically.

Troubleshooting

Port already in use

The local port is occupied. Use a different port or an ephemeral port:

cpln port-forward my-db :5432

Connection refused

The workload may not be listening on that port. Verify the container port:

cpln workload get my-db --output yaml

Check the ports section in the container spec.

No replicas found

The workload may not be running in the specified location:

cpln workload replica get my-db

Try a different location or wait for replicas to start.

Permission denied

You need connect permission on the workload. Check your policies.

Next steps

Connect to Workloads

Interactive shell access

Execute Commands

Run commands in containers

Copy Files

Transfer files to/from workloads

Command Reference

Full port-forward command reference

How-to Guides

CLI Configuration

Integrations

Configure Resources

Create Resources

Deployment

GitOps

Images

Native Networking

Observability

Sandbox

Workload Access

Port Forward to Workloads

When to use this

Access databases

Debug internal services

Local development

Private service access

Prerequisites

Basic usage

Options

Port format options

Forward multiple ports

Listen on multiple addresses

Target specific locations

Common workflows

Connect to PostgreSQL

Access Redis

Debug a web service

Access admin panels

Port forwarding to unexposed ports

Troubleshooting

Next steps

Connect to Workloads

Execute Commands

Copy Files

Command Reference

​When to use this

Access databases

Debug internal services

Local development

Private service access

​Prerequisites

​Basic usage

​Options

​Port format options

​Forward multiple ports

​Listen on multiple addresses

​Target specific locations

​Common workflows

​Connect to PostgreSQL

​Access Redis

​Debug a web service

​Access admin panels

​Port forwarding to unexposed ports

​Troubleshooting

​Next steps

Connect to Workloads

Execute Commands

Copy Files

Command Reference

When to use this

Prerequisites

Basic usage

Options

Port format options

Forward multiple ports

Listen on multiple addresses

Target specific locations

Common workflows

Connect to PostgreSQL

Access Redis

Debug a web service

Access admin panels

Port forwarding to unexposed ports

Troubleshooting

Next steps