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

​
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:

​
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:
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.

​
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 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 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

​
Find the protocol version of an agent

​
UI Console

  1. Click Agents in the left menu.
  2. Click 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.

​
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, see the agent CLI reference.