Skip to main content

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.

​
Overview

In situations where your workload needs to consume services from endpoints within a VPC or another private network, you would 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 will follow only v2 protocol.

​
New Features in Protocol Version v2

  • faster deploy time of agent
  • better isolation at the VPN layer
  • load-balancing across agent instances
  • no need for public IPs on your BYOK locations
  • you can use your favorite/hardened Linux base image on the hyperscalers

​
Find protocol version of an agent

​
UI Console

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

​
CLI

  1. Execute the following command to get an agent
cpln agent get <agent> -o yaml
  1. 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.

​
Setup Agent

​
Create and Set up an Agent v2

Visit one of the links below for a step-by-step guide on how to create an agent with a specific provider:

​
Create and Set up an Agent v1

v1 is deprecated. Please refer to the updated Configure an Agent guide, unless you created you argent before April 2026
Visit one of the links below for a step-by-step guide on how to create an agent with a specific provider:
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)

Agents run in active-passive mode. If an active agent misses a set amount of heartbeats, it is considered offline and replaced by a redundant agent. 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 VMSS/virtual machine scale set 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 set to a minimum of 2 and a maximum of the number of zones used within your infrastructure.

​
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 TypeAverage Bandwidth (MB/sec)Average Latency (us)Baseline Bandwidth (Gbps)
    No Agent307.6585.6n/a
    t2.micro21.2313010.064
    t3.small143.911070.128
    c5.large341.1629.60.75
    c4.xlarge70.25680.85.0
    When capacity planning the Baseline Bandwidth should be used instead of the Burst Bandwidth.
    Available Baseline Bandwidth for each instance can be discovered 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 TypeAverage Bandwidth (MB/sec)Average Latency (us)
    No Agent313.4251.2
    n2-standard-2250.3407.7
    n2-standard-8223.3350.7
    n2-standard-4217.5354.1
    n1-standard-1199.9409.3

​
Permissions

The permissions below are used to define policies together with one or more of the four principal types:
PermissionDescriptionImplies
createCreate new agents
deleteDelete service agents
editModify existing agentsview
manageFull accesscreate, delete, edit, manage, use, view
useUse an agent in an identityview
viewRead-only access

​
Access Report

Displays the permissions granted to principals for the agent.

​
CLI

To view the CLI documentation for an agent, click here.