Connect your own network (VPN gateway)

Reach the services on a private network from your laptop, your office or another cloud, by alias, through a WireGuard gateway you open from the Networks page.

What it does

Every application, database and service you deploy runs on a private network: a VXLAN overlay that nothing outside the cluster can see. Inside it, services reach each other by alias - api, db, redis - without ports being published anywhere.

A gateway extends that network to you. Open one on a network and any device or site in the world can join it as a peer: a laptop, a phone, your office router, a VPC in another cloud. A peer then reaches the services on the network directly, with no public exposure, and resolves them by name exactly as your containers do:

curl http://api:8000/health          # bare alias, through the gateway's resolver
curl http://api.app-tier.isogrid.internal:8000/health   # or under the network's zone
psql -h db -U app                    # a database that is not published at all

The tunnel is WireGuard - the VPN built into the Linux kernel, with first-party clients for Windows, macOS, iOS and Android and support in most routers (MikroTik, OPNsense, pfSense, OpenWrt, Ubiquiti) and cloud VPN gateways. There is no agent to install on your servers and no account with a third party: a connection is two key pairs and a UDP port.

Opening a gateway

On the Networks page, the VPN connections button on one of your networks opens the panel. Click Create VPN gateway. In a few seconds it shows:

  • the endpoint peers connect to (an address and a UDP port);
  • the resolver, the gateway's own address inside the tunnel;
  • the name suffix, <network>.isogrid.internal, under which every alias on the network also answers;
  • the private network's own subnet, which peers route through the tunnel.

Only the network's owner can open a gateway, and the region has to sell them: a gateway that cannot be created yet says so, and the operator prices it per region.

The tunnel's own addresses are chosen for you in shared address space (100.64.0.0/10), which no office or cloud network uses, so they never collide with a peer's LAN. Set them yourself only if yours does.

Adding a peer

A peer is one device or one site. Give it a name and, for a site, the subnets behind it; leave those empty for a laptop or a phone. Each peer gets its own key pair and preshared key, and a configuration to import:

  • A laptop or phone. Install WireGuard, import the configuration (the phone apps scan the QR code), switch it on. Services then resolve by alias, bare or under the zone, through the gateway's resolver.
  • A whole site or VPC. Load the configuration on the router or cloud VPN gateway, with the subnets behind it declared on the peer. Then forward the zone <network>.isogrid.internal to the resolver's address in your DNS so that every machine on the site resolves the services without changing its own resolver.

The configuration contains the peer's private key. Treat it like a password: import it, then fetch it again here when needed rather than keeping copies in chat or on a share.

Rotating keys

Keys never sit in a configuration you cannot replace. Two rotations exist, and either takes effect in the few seconds the gateway needs to restart:

  • Rotate a peer's keys replaces that one peer's key pair and preshared key. Its current configuration stops working; import the new one on the device. Nobody else notices. This is what to do when one device was lost or one configuration leaked.
  • Rotate the gateway's keys replaces the gateway's own key pair. Every peer's configuration contains it, so every peer has to import a fresh one. This is the rotation for "we do not know what leaked".

A peer can also be disabled, which keeps it out without deleting it, and removed. Each of these is a few seconds of interruption for every peer, during which WireGuard clients retry on their own and reconnect.

What a peer can and cannot do

The gateway is a door in, not a door out:

  • A peer reaches the private network's subnet and the gateway's resolver, and nothing else: not the cluster's nodes, not the internet through the gateway, not other peers.
  • Traffic flows from your network into the private network. Services on the network do not reach back into your LAN.
  • Which addresses a peer may send from is enforced by WireGuard itself from the peer's declared subnets, before any firewall rule.
  • Every tunnel uses a preshared key on top of the key pairs, so a session stays private even against someone who could one day break the public-key exchange.

Each peer's last handshake and traffic counters are shown on the panel (Refresh status asks the cluster), which is how you tell a site that is connected from one that is not.

From the command line

isogrid networks gateway open  --network app-tier
isogrid networks peers add laptop --network app-tier --out .
isogrid networks peers add office --network app-tier --subnet 192.168.1.0/24 --out office.conf
isogrid networks gateway show  --network app-tier --live
isogrid networks peers rotate laptop --network app-tier --out .
isogrid networks gateway rotate --network app-tier

See the CLI reference for every flag.

Troubleshooting

The peer handshakes but nothing resolves. The client is not using the gateway's resolver. On a device, keep the DNS line of the configuration; on a site, forward the zone to the resolver's address, or use the private network's addresses directly.

The handshake never completes. UDP to the endpoint is blocked somewhere on your side (a corporate firewall, a mobile carrier). WireGuard only needs one UDP port out; the endpoint's port is shown on the panel.

Services resolve but connections hang. The private network's subnet collides with a subnet on your side, so the route goes the wrong way. Create the network with a subnet of your own choosing, or re-address the colliding side.

The gateway shows an error. The region's node may lack the WireGuard kernel module or run an old Docker; the operator sees the exact message in the admin console and the task state is shown on the panel.