Agent - Control Plane

Overview

In situations where your workload needs to consume services from endpoints within a VPC or another private network, you can use a wormhole agent. Control Plane’s wormhole technology securely connects your workloads to any TCP or UDP endpoints in VPCs and other private networks, including on-prem data centers and even on a developer’s laptop. You establish a wormhole by running an agent VM (agent for short) inside the private network to which you are connecting your workloads. Control Plane offers agents for both private networks and cloud providers. The agent is installed and configured within the location where it can access the applications or services that your workload requires. It does this by establishing a secure and persistent connection to publicly hosted Control Plane servers. Requests from your workload are tunneled to the agent, which performs the request, and then tunnels the response back. This flow occurs in a performant manner and is transparent to the workload. Agents are scoped to an org and are used in conjunction with identities to set up network resources.

Protocol Version 2

Control Plane updated agents in April 2026 to support new features and enhance performance. If your agent was created before the update, it is running protocol version v1. If it was created after the update, it is running protocol version v2. Version v1 is still supported but newly created agents use protocol version v2 only.

New Features

Faster agent deployment times.
Better VPN-layer isolation.
Load-balancing across agent instances.
No need for public IPs on your BYOK locations.
Use your preferred hardened Linux base image on supported hyperscalers.
Bi-directional functionality.

Setup Agent

Create and Set up an Agent v2

Use one of the following guides for step-by-step instructions on how to create an agent with a specific provider:

Amazon Web Services (AWS)
Microsoft Azure
Google Cloud Platform (GCP)
Docker (e.g., private data centers, internal web services, developer’s laptop, etc.)
Kubernetes (k8s) Cluster

Create and Set up an Agent v1

v1 is deprecated. Use the updated Configure an Agent guide unless your agent was created before April 2026.

Use one of the following guides for step-by-step instructions on how to create an agent with a specific provider:

Amazon Web Services (AWS)
Microsoft Azure
Google Cloud Platform (GCP)
Private Network (e.g., private data centers, internal web services, developer’s laptop, etc.)
Kubernetes (k8s) Cluster

If you are running a legacy version of the agent (protocol version v1 in the UI), you will need to follow the legacy agent setup guide to set up your agent.

High Availability (HA)

Version 2 agents run in active-active mode. If an agent misses a set amount of heartbeats, it is considered offline and the remaining active agents continue handling work until the instance group automatically replaces it. The recommended method to configure a highly available agent deployment is by using an instance group (also called an autoscaling group on AWS or a virtual machine scale set (VMSS) on Azure). The autoscaling group template must be configured in the same way as a single VM in terms of cloud configuration, network settings, etc. As the agent’s functionality is not CPU intensive, that metric cannot be used to scale instances up and down. Instead, use a fixed-sized group with a minimum of 2 and a maximum equal to the number of zones in your infrastructure.

Bi-directional Functionality

Version 2 includes a proxy server that listens on port 3128. It allows applications running inside the private network where the agent is deployed to call workloads running on Control Plane without opening external firewall access or allowlisting the private network’s outbound Internet IP. Use this when systems inside your private network need to initiate outbound calls to workloads running on Control Plane without exposing those workloads broadly to the Internet.

Bi-directional functionality helps enforce least-privilege access to workloads running on Control Plane, which can support compliance requirements.

Configuration

To allow an agent to proxy a request to the workload running on Control Plane, follow these steps:

Click Workload in the left menu and select the workload the agent will be call.
Click Firewall, then click the Internal tab.
Click Inbound Allow Type and select either Workload List or Same GVC & Workload List, depending on your requirements.
Click Add Agent and select one or more agents. Click OK.
Click Update. Once the deployment is complete, the agent will be allowed to proxy requests to this workload.

Proxy Usage

To route traffic through the proxy, configure the calling application to use the agent’s internal IP address and port 3128 as its HTTPS proxy. Obtain the agent’s internal IP address from the instance summary page for the cloud provider where the agent is deployed.

Curl example

HTTPS_PROXY=http://AGENT_IP:3128 curl https://example-cpln-workload.cpln.app

If you are not able to configure the application to use the proxy server, the global proxy server setting of the running environment can be configured.

export HTTPS_PROXY=http://AGENT_IP:3128

Set this environment variable in the running profile if you want it to persist after the environment restarts.

Even if the global proxy server is set to the agent, only requests to the selected workload on Control Plane are proxied. All other requests bypass the proxy.

Agent Sizing Guidance

When utilizing an agent, the machine type running the agent affects the bandwidth and latency exhibited by the agent. The tables below are provided to help guide your agent machine type selection. Tests were performed using qperf. The qperf client was configured as a container workload running on the Control Plane platform and deployed in the same region as the qperf server running on a virtual machine. Based on the results below, select an agent type suitable for your performance requirements.

AWS

Region tested: aws-us-west-2
qperf server running on: c5.2xlarge instance type
Test runtime: 30 seconds

Agent Instance Type	Average Bandwidth (MB/sec)	Average Latency (us)	Baseline Bandwidth (Gbps)
No Agent	307.6	585.6	n/a
t2.micro	21.23	1301	0.064
t3.small	143.9	1107	0.128
c5.large	341.1	629.6	0.75
c4.xlarge	70.25	680.8	5.0

When capacity planning the baseline bandwidth should be used instead of the burst bandwidth.

Available baseline bandwidth for each instance can be found using the AWS CLI. This query shows the BaselineBandwidthInGbps for t3 instances. Adjust as needed for the instance types required.

  aws ec2 describe-instance-types \
  --filters "Name=instance-type,Values=t3.*" \
  --query "InstanceTypes[].[InstanceType, NetworkInfo.NetworkCards[0].BaselineBandwidthInGbps] | sort_by(@,&[1])" \
  --output table

  -------------------------
  | DescribeInstanceTypes |
  +-------------+---------+
  |  t3.nano    |  0.032  |
  |  t3.micro   |  0.064  |
  |  t3.small   |  0.128  |
  |  t3.medium  |  0.256  |
  |  t3.large   |  0.512  |
  |  t3.xlarge  |  1.024  |
  |  t3.2xlarge |  2.048  |
  +-------------+---------+

GCP
- Region tested: gcp-us-east1
- qperf server running on: e2-standard-8 machine type
- Test runtime: 30 seconds
Agent Machine Type Average Bandwidth (MB/sec) Average Latency (us)
No Agent 313.4 251.2
n2-standard-2 250.3 407.7
n2-standard-8 223.3 350.7
n2-standard-4 217.5 354.1
n1-standard-1 199.9 409.3

Agent Machine Type	Average Bandwidth (MB/sec)	Average Latency (us)
No Agent	313.4	251.2
n2-standard-2	250.3	407.7
n2-standard-8	223.3	350.7
n2-standard-4	217.5	354.1
n1-standard-1	199.9	409.3

Find the protocol version of an agent

UI Console

Click Agents in the left menu.
Click the agent name to view the agent details page.
The protocol version is displayed in the Summary section.

CLI

Execute the following command to get an agent:

cpln agent get <agent> -o yaml

The protocol version can be found in the status.protocolVersion field. If the field is not present, the agent is running protocol version v1. If the field is present and has a value of v2, the agent is running protocol version v2.

Permissions

The permissions below are used to define policies together with one or more of the four principal types:

Permission	Description	Implies
create	Create new agents
delete	Delete service agents
edit	Modify existing agents	view
manage	Full access	create, delete, edit, manage, use, view
use	Use an agent in an identity	view
view	Read-only access

Access Report

Displays the permissions granted to principals for the agent.

CLI

To view the CLI documentation for an agent, see the agent CLI reference.

​Overview

​Protocol Version 2

​New Features

​Setup Agent

​Create and Set up an Agent v2

​Create and Set up an Agent v1

​High Availability (HA)

​Bi-directional Functionality

​Configuration

​Proxy Usage

​Agent Sizing Guidance

​Find the protocol version of an agent

​UI Console

​CLI

​Permissions

​Access Report

​CLI

Overview

Protocol Version 2

New Features

Setup Agent

Create and Set up an Agent v2

Create and Set up an Agent v1

High Availability (HA)

Bi-directional Functionality

Configuration

Proxy Usage

Agent Sizing Guidance

Find the protocol version of an agent

UI Console

CLI

Permissions

Access Report

CLI