Agent Setup

Tool availability: the agent lifecycle tools — create_agent / update_agent, get_agent_info / get_agent_eventlog, and add_identity_network_resource / add_identity_native_network_resource / remove_identity_network_resource / list_identity_network_resources — live in the `full` toolset profile. create_identity / update_identity / update_workload and all reads/deletes (list_resources, get_resource, delete_resource) are core. If a full tool is not advertised, reconnect the MCP server with ?toolsets=full, or use the cpln agent CLI.

A wormhole agent is a lightweight VM or container you run inside the target network. It opens a persistent outbound connection to Control Plane and tunnels workload traffic to any TCP/UDP endpoint on the private side — VPC, on-prem, data center, Azure VNet, cross-cloud, or a laptop. A workload reaches the endpoint by attaching an identity (gvc-scoped) that carries a networkResources entry pointing at the agent. No external egress firewall rule is needed.

Scope: this is the deploy walkthrough — create the agent, deploy it on your platform, wire up the identity, verify. For the PrivateLink/PSC-vs-agent comparison, agent sizing tables, the full identity schema, and agent permissions, read native-networking. For the cloud-credential side (AWS/GCP/Azure access without an agent), read setup-cloud-access.

Before you start

Confirm with the user: what private resource the workload must reach (host/IP + ports), where it lives (cloud/VPC/on-prem/cluster), the org, and whether an agent already exists (list_resources kind="agent"). Reach for an agent only when PrivateLink/PSC does not fit — for an AWS or GCP managed service, native networking is lower-latency and needs no agent (see native-networking). An agent is right for on-prem, cross-cloud, Azure, or local development.

Step 1 — Create the agent

If the user asked you to set one up, create it directly; only list first when they want to reuse an existing one. Call create_agent (org, name, optional description / tags). The response contains the bootstrap config JSON — copy it out immediately.

CLI fallback (pipes the bootstrap straight to a file):

cpln agent create --name AGENT --org ORG > AGENT-bootstrap.json

Save the bootstrap config now. It holds the registration token and is shown only once, at creation. Reads (get_resource kind="agent") return it with the token hidden. It is immutable — if lost, delete and recreate the agent. update_agent changes description / tags only.

Step 2 — Deploy the agent

Pick the target; each artifact path is CLI/console (no MCP equivalent). Deploy in the same VPC/region as the target, with outbound internet and no inbound ports required.

Never run two replicas of one deployment. Each deployment has a unique key; duplicating it causes intermittent latency and dropped packets. For HA, run separate deployments (K8s --replicas 2; cloud VMs in a fixed-size instance group / ASG / VMSS). Agents run active-active — every instance serves traffic, and a missed-heartbeat instance is dropped while the group replaces it. The agent is not CPU-intensive — do not autoscale on CPU; size the group min 2, max = number of availability zones.

The agent also exposes a proxy on port 3128 (cpln agent up --exposeProxy) so systems inside the private network can call Control Plane workloads without external firewall changes — grant it on the workload's Internal firewall (see firewall-networking).

Step 3 — Wire the identity to the agent

A workload routes through the agent only when an identity carrying a networkResources entry is attached to it. Create the identity first if it does not exist (create_identity, see access-control).

Add the agent-based resource with add_identity_network_resource (org, gvc, identity, one resource):

{
  "org": "ORG", "gvc": "GVC", "identity": "IDENTITY",
  "resource": {
    "name": "on-prem-db",
    "agentLink": "//agent/AGENT",
    "IPs": ["10.0.1.50"],
    "ports": [5432]
  }
}

Key constraints (Joi-enforced; mirrored by the tool): name unique across both networkResources and nativeNetworkResources and never equal to a FQDN; IPs (1-5 IPv4) xor FQDN (exactly one); ports 1-10, each 0-65535; optional resolverIP for private DNS; max 50 per array. update_identity replaces the whole array; remove_identity_network_resource deletes by name from either array (destructive — confirm first).

For a local Docker agent, set the resource IPs to the host's Docker network-adapter IP, never localhost / 127.0.0.1.

Attach the identity to the workload: update_workload setting spec.identityLink to //identity/IDENTITY. Without the attachment, nothing routes.

Step 4 — Verify

• get_agent_info — lastActive within 60s means active; check peerCount and serviceCount. get_agent_eventlog shows connection events and errors. (CLI: cpln agent info|eventlog AGENT --org ORG.)
• list_identity_network_resources confirms the entry is on the identity.
• From the workload, dial the resource `name` (e.g. nc -zv on-prem-db 5432 via workload_exec). For a TLS target, connect on the FQDN, not the name — the certificate is issued for the FQDN.

Common mistakes

• Wrong deploy command — cpln agent up is Docker hosts; cpln agent manifest is K8s; cloud VMs use the marketplace image + bootstrap as user-data (no cpln command).
• Losing the bootstrap config — output once at creation; if lost, delete and recreate.
• Scaling one deployment past 1 replica — drops packets; use separate deployments.
• Missing `agentLink`, or `localhost` for a local agent's IP — traffic cannot route.
• Forgetting `spec.identityLink` — the identity is wired but never reaches the workload.
• Using `name` instead of `FQDN` for a TLS endpoint — certificate validation fails.

Related skills

Documentation

• Agent Reference · Agent Setup Guide
• Identity Reference