AnkraDocs
Console

Concepts

VPN gateways

Reach one or more private networks of a zone from laptops, phones and remote sites, over plain WireGuard or with the Tailscale apps through Headscale.

A VPN gateway is a managed VM with a leg on each of 1 to 7 private networks of one zone. Devices and remote networks connect to it and reach every one of those networks. Like an edge, the gateway VM is managed by Ankra: it does not appear among your servers and you cannot SSH into it.

Two modes#

Every gateway has a mode, chosen at creation:

Mode How devices connect Choose it when
wireguard (the default) Any WireGuard client. You add each device or site as a peer by its public key and give it a configuration file. You want plain WireGuard, connect whole remote sites, or have no DNS name to spare.
headscale The Tailscale apps, against a Headscale control server on the gateway. Devices join with a key; devices also reach each other. You want the Tailscale apps on laptops and phones, and joining a device should take one key.

Either way, traffic from the VPN is masqueraded onto the gateway's own address on each network. Your servers see VPN traffic coming from that address, so they need no route, firewall change or agent of their own. Nothing is forwarded to the internet or between the gateway's networks.

WireGuard mode#

Peers#

A peer is one of two kinds:

Kind What it is
client A single device: a laptop, a phone, a server elsewhere. It gets one address in the tunnel network.
site A router of a remote network. It names the IPv4 networks behind it in remote_networks, and those networks reach the gateway's networks too. Give it an endpoint and a keepalive when the gateway must reach it first.

Each peer gets the next free address of the gateway's tunnel network (10.254.0.0/24 unless you choose another one at creation). Peers do not reach each other.

Add my device#

Add my device on the gateway's page connects the device you are on in one step. The console makes the key pair in your browser, registers a client peer with mine: true so it is listed as yours (is_mine, owner_user_id), and fills the private key into the configuration right there, once:

  • macOS and Windows: install the WireGuard app and import the downloaded file;
  • Linux: download the file and run sudo wg-quick up ./<name>.conf;
  • iPhone, iPad and Android: scan the QR code with the WireGuard app. The code is drawn in your browser and holds the private key, so show it only to your own phone.

The peers list shows yours first (Mine) and everyone's on request. Add a peer manually stays for a key made with wg genkey and for remote sites.

Keys never leave the device#

The gateway generates its own WireGuard key on its VM; only its public key (public_key) is ever reported. A peer is registered by its public key alone:

  • Make the key pair on the device with wg genkey | tee peer.key | wg pubkey and paste the public key, or
  • let the console generate the pair in your browser. The private key goes straight into the configuration file you download and is never sent to Ankra; it is shown once.

GET /v1/vpn-gateways/{id}/peers/{peer}/configuration returns a ready wg-quick file with the gateway's public key, endpoint and every network as AllowedIPs. Its PrivateKey line holds a placeholder for the peer's own key. The endpoint answers 409 until the gateway has generated its key.

bash
curl -X POST https://cloud.ankra.app/v1/vpn-gateways \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "network_ids": ["<network-id>", "<another-network-id>"], "plan": "starter-1c-1g" }'

curl -X POST https://cloud.ankra.app/v1/vpn-gateways/<id>/peers \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "laptop", "kind": "client", "public_key": "<output of wg pubkey>" }'

Every peer change is one vpn_gateway.sync operation and does not drop the other peers' sessions. With public_ipv4 (the default), peers dial <ipv4>:51820; without it they connect over IPv6.

Headscale mode#

A DNS name you control#

A headscale gateway serves a hostname in a domain you control, which is required at creation. The last step is yours: once the gateway has its addresses, create two records where your domain's DNS is hosted:

  • A from the hostname to the gateway's public_ipv4,
  • AAAA from the hostname to its public_ipv6.

The gateway obtains its own certificate once the name points at it. Until then keys and the device list answer 409. The Tailscale apps log in to login_server, https://<hostname>.

GET /v1/vpn-gateways/{id} carries this step as dns once the gateway has its addresses: the records to create, is_ready (whether the name resolves to every record's address now, checked at most every 30 seconds), one sentence of instructions and, while it is not ready, the problem. dns is null for a wireguard gateway, in lists and before the gateway has addresses. Creating a headscale gateway also sends a notification with the same records.

In the console, the gateway's page opens with this step:

  • While the gateway is still being created, it says the addresses are coming.
  • Then a One step left banner lists the records with copy buttons and what is still wrong. The page checks again every 15 seconds, and Check again checks at once. DNS changes can take a few minutes to reach everyone.
  • Once the name points at the gateway, the banner says so and offers Add device.
bash
curl -X POST https://cloud.ankra.app/v1/vpn-gateways \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "network_ids": ["<network-id>"], "mode": "headscale", "hostname": "vpn.example.com" }'

Joining devices#

Every device belongs to a user on the tailnet: your own devices are filed under your email, and shared ones, such as servers and CI runners that are nobody's own, under the shared user devices.

Connect this device on the gateway's page is the quick way for your own laptop or phone. It picks your platform from the browser and:

  • on macOS, Windows and Linux, makes a personal key that joins once and expires in an hour, and shows the one command to paste into a terminal, with the key in it;
  • on iPhone, iPad and Android, shows how to sign in to the login server in the Tailscale app. The app then shows a code; paste it into the dialog and the phone is registered to you (POST /v1/vpn-gateways/{id}/devices with registration_key). No key is needed on a phone.

The dialog says Connected as soon as the new device shows up.

Create a key manually is for everything else. POST /v1/vpn-gateways/{id}/auth-keys makes a pre-auth key: for your own devices by default, or for the shared user with shared: true. A reusable key joins many devices, an ephemeral one joins devices that are removed again when they go offline, and expiration_hours (1 to 2160, 24 by default) is how long the key may be used to join; devices that joined stay. The key is in that answer only: Ankra keeps no copy. The answer also carries user, join_command for Linux and install, the command or steps for each of Linux, macOS, Windows, iOS and Android.

The gateway is the tailnet's subnet router for its networks. GET /v1/vpn-gateways/{id}/devices lists the devices that joined, each with its user and is_mine; the console shows yours first (Mine) and everyone's on request. DELETE /v1/vpn-gateways/{id}/devices/{device} logs one out; it joins again only with a new key. No Headscale credential leaves the gateway VM.

Limits#

  • The mode and the networks are fixed at creation, all networks in one zone. To reach another set, create another gateway.
  • Servers cannot initiate connections to a site's networks or to devices yet; connections start from the VPN side.
  • WireGuard: a site names at most 16 remote networks; the tunnel network is a private IPv4 network (or 100.64.0.0/10) from /16 to /28 that does not overlap the gateway's networks. The peers endpoints answer 409 for a headscale gateway.
  • Headscale: keys and devices answer 409 for a wireguard gateway.

Pricing#

A gateway is billed at its plan plus the public IPv4 add-on when it has one. Peers and devices are not billed.