> ## 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.
# Agent
> Reference for Control Plane agents used to connect workloads to private networks, including protocol versions, high availability, sizing guidance, and permissions.
## Overview
In situations where your [workload](/concepts/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](/concepts/workload) 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](/concepts/workload).
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](/concepts/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](/concepts/workload).
Agents are scoped to an [org](/reference/org) and are used in conjunction with [identities](/reference/identity) to set up [network resources](/reference/identity#network-resources-cloud-wormhole).
## 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:
* [Amazon Web Services (AWS)](/guides/setup-agent#aws)
* [Microsoft Azure](/guides/setup-agent#azure)
* [Google Cloud Platform (GCP)](/guides/setup-agent#gcp)
* [Docker](/guides/setup-agent#running-locally-in-docker) (e.g., private data centers, internal web services, developer's laptop, etc.)
* [Kubernetes (k8s) Cluster](/guides/setup-agent#kubernetes-k8s-cluster)
### Create and Set up an Agent v1
`v1` is deprecated. Use the updated [Configure an Agent](/guides/setup-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)](/guides/setup-agent-legacy#aws)
* [Microsoft Azure](/guides/setup-agent-legacy#azure)
* [Google Cloud Platform (GCP)](/guides/setup-agent-legacy#gcp)
* [Private Network](/guides/setup-agent-legacy#private-network) (e.g., private data centers, internal web services, developer's laptop, etc.)
* [Kubernetes (k8s) Cluster](/guides/setup-agent-legacy#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](/guides/setup-agent-legacy) 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](https://github.com/linux-rdma/qperf/blob/master/src/help.txt). 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.
```bash theme={null}
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 |
## 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:
```bash theme={null}
cpln agent get -o yaml
```
2. 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](/reference/policy) together with one or more of the four [principal types](/concepts/access-control):
| 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](/cli-reference/commands/agent).