Skip to main content
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

Install the Control Plane CLI. See Installation.
You need a running workload in at least one location. See the Create a Workload guide.
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.

​
Options

OptionDescription
--addressLocal addresses to listen on, comma-separated (default: localhost)
--locationTarget location (defaults to first available in GVC)
--replicaTarget a specific replica (defaults to any available)

​
Port format options

Map a different local port to the remote port:
cpln port-forward my-db 5433:5432
Access the database at localhost:5433.

​
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

The local port is occupied. Use a different port or an ephemeral port:
cpln port-forward my-db :5432
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.
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.
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