WireGuard Interfaces Quick Start

Prerequisites

A host with WireGuard installed: Linux, macOS, or Windows.
A region that offers WireGuard Interfaces. GET /v2/network_coverage?filter[available_services][contains]=cloud_vpn lists them. A location’s location.code, such as ashburn-va, is the region_code to use.
A Network. POST /v2/networks with {"name": "acme-prod"} returns its id.

Create the interface

Send POST /v2/wireguard_interfaces:

{
  "network_id": "0de011ae-ee53-4df4-ba96-754728eb5aad",
  "name": "wg-ashburn",
  "region_code": "ashburn-va"
}

An interface cannot move to another Network. Confirm network_id before sending the request.

The response returns status: provisioning and the values that peers need: endpoint, public_key, and server_ip_address.

{
  "data": {
    "name": "wg-ashburn",
    "status": "provisioning",
    "created_at": "2026-10-09T23:03:28.957851Z",
    "region_code": "ashburn-va",
    "enable_sip_trunking": false,
    "public_key": "dM4BrhaKqRVoq+mMD+4mmQ5KTFkcutiXnfN2Ztk+3Sw=",
    "id": "749de8c6-bbd0-42dd-9a16-770a519b565d",
    "updated_at": "2026-10-09T23:03:31.009085Z",
    "network_id": "0de011ae-ee53-4df4-ba96-754728eb5aad",
    "region": {
      "code": "ashburn-va",
      "name": "Ashburn VA, US",
      "record_type": "region"
    },
    "record_type": "cloud_vpn",
    "endpoint": "64.16.243.3:5134",
    "server_ip_address": "172.27.0.1/24"
  }
}

Wait for provisioning

Poll GET /v2/wireguard_interfaces/{id} until status is provisioned. This takes a few minutes. Peers can be added once it is provisioned.

Create a peer

{
  "name": "laptop",
  "wireguard_interface_id": "749de8c6-bbd0-42dd-9a16-770a519b565d"
}

Telnyx generates the host’s key pair and returns its private_key once, in this response. Store it.

{
  "data": {
    "name": "laptop",
    "created_at": "2026-10-09T23:06:14.665447Z",
    "public_key": "mOlLNRWGCiSkXpBXKMeC6QvTNRTb7lVMaa/GrOIskm8=",
    "updated_at": "2026-10-09T23:06:15.052007Z",
    "last_seen": null,
    "wireguard_interface_id": "749de8c6-bbd0-42dd-9a16-770a519b565d",
    "id": "79701b5e-9d7f-4dd1-8b80-45bae4304856",
    "record_type": "wireguard_peer",
    "private_key": "<peer private key>"
  }
}

To keep the private key on the host instead, generate the key pair there and send only the public key as public_key. The response then has no private_key.

umask 077
wg genkey | tee peer.key | wg pubkey

Configure the host

GET /v2/wireguard_peers/{id}/config returns a configuration template as plain text:

# Telnyx CloudVPN config. Target OS: Linux

[Interface]
PrivateKey = <! INSERT PEER PRIVATE KEY HERE !>
Address = 172.27.0.2/32

[Peer]
PublicKey = dM4BrhaKqRVoq+mMD+4mmQ5KTFkcutiXnfN2Ztk+3Sw=
AllowedIPs = 172.27.0.0/24
Endpoint = 64.16.243.3:5134
PersistentKeepalive = 1

The file describes the tunnel from the host’s side: [Interface] is the local host itself, and [Peer] is the WireGuard Interface in Telnyx.

Section	Field	Value
`[Interface]`	`PrivateKey`	The host’s private key, in place of the placeholder.
`[Interface]`	`Address`	The host’s address on the WireGuard Interface’s subnet. The first host gets the address after the WireGuard Interface.
`[Peer]`	`PublicKey`	The WireGuard Interface’s `public_key`.
`[Peer]`	`AllowedIPs`	The prefixes that the host routes via the tunnel, starting with the WireGuard Interface’s subnet.
`[Peer]`	`Endpoint`	The WireGuard Interface’s `endpoint`.
`[Peer]`	`PersistentKeepalive`	How often, in seconds, the host sends a keepalive to the WireGuard Interface.

Replace the placeholder with the host’s private key and save the file as /etc/wireguard/wg0.conf. On Linux, bring the tunnel up:

sudo wg-quick up wg0

Verify

sudo wg show lists the local host as interface and the WireGuard Interface in Telnyx as peer, with a recent handshake:

interface: wg0
  public key: mOlLNRWGCiSkXpBXKMeC6QvTNRTb7lVMaa/GrOIskm8=
  private key: (hidden)
  listening port: 48065

peer: dM4BrhaKqRVoq+mMD+4mmQ5KTFkcutiXnfN2Ztk+3Sw=
  endpoint: 64.16.243.3:5134
  allowed ips: 172.27.0.0/24
  latest handshake: 1 second ago
  transfer: 124 B received, 180 B sent
  persistent keepalive: every 1 second

The WireGuard Interface answers on its address:

ping -c 3 172.27.0.1

GET /v2/wireguard_peers/{id} reports the peer’s last_seen time.

Get Started

Configure Peers

Use Cases

API Reference

For AI Agents

WireGuard Interfaces Quick Start

Prerequisites

Create the interface

Wait for provisioning

Create a peer

Configure the host

Verify

​Prerequisites

​Create the interface

​Wait for provisioning

​Create a peer

​Configure the host

​Verify

Prerequisites

Create the interface

Wait for provisioning

Create a peer

Configure the host

Verify