Plan your Tunnex deployment

This is the preflight checklist for the person who will own the deployment. Do not start with the installer and discover the network design afterward: the public URL, gateway reachability, address pools, and recovery custody become part of issued client state.

Tunnex is self-hosted. It does not provide a hosted traffic relay or managed NAT traversal fleet. A gateway can call the control plane from behind NAT, but clients and other sites cannot initiate WireGuard traffic to that gateway unless you provide a reachable UDP endpoint or port forward.

For the public Compose installer, prepare a dedicated Linux host with:

• an amd64 or arm64 CPU;
• Docker Engine and Docker Compose v2;
• curl and openssl;
• correct DNS and time synchronization; and
• durable storage for PostgreSQL and the Tunnex secrets volume.

Two vCPUs and 2 GB of RAM are a reasonable evaluation starting point, not a production sizing guarantee. Size from your actual device count, audit volume, retention, and database monitoring.

Run these checks before installing:

uname -m
docker version
docker compose version
timedatectl status
getent hosts vpn.example.com

Use one stable public origin such as https://vpn.example.com. Direct HTTPS to a raw IP is rejected by the installer because certificate management needs a DNS name.

Open the same rules in the provider firewall, host firewall, and any intervening NAT device. A healthy HTTPS page proves only TCP reachability; it does not prove that 51820/udp reaches the gateway.

Choose non-overlapping ranges for:

• the organization device pool;
• each site’s private LANs;
• Kubernetes Service CIDRs and synthetic VIP pools; and
• optional IPv6 pools.

The Routed ranges page is the source of truth after deployment, but it is read-only. Pending site advertisements are approved under Sites. Do not interpret a partially loaded inventory as proof that a range is free.

• Managed macOS and Windows clients can report posture. Linux CLI, imported WireGuard/OpenVPN profiles, iOS, and Android do not provide managed posture.
• Static/imported profiles bake in routes and DNS. Re-export and re-import them after a route, DNS, or gateway-home change that cannot be delivered in place.
• Full tunnel requires an egress-capable gateway and working return routing.
• Access rules do nothing until enforcement is enabled. Enforcement is default-deny, so an omitted recovery rule can lock operators out of the data plane.
• Network policy limits where an AI agent can connect; it cannot inspect prompts or detect prompt injection. MCP tool policy applies only through the explicit local MCP proxy.

A usable control-plane recovery set has two separately protected artifacts:

1. a PostgreSQL custom-format dump; and
2. the exact 32-byte Tunnex master key.

Losing the master key makes sealed CA, MFA, SSO, and OpenVPN material unrecoverable even when the database dump is intact. Gateway and device private keys are generated on their hosts and are not in the control-plane backup.

Before adding real users, be able to answer yes to all of these:

• The public URL resolves from every user network.
• HTTPS, TCP 8443, and the chosen WireGuard UDP port were tested independently.
• Site, device, Kubernetes, and VIP ranges do not overlap.
• At least two people know how to access the host out of band.
• The master key and database dump have separate, tested custody.
• SMTP or an explicit manual invitation/reset process is available.
• A representative allowed flow and denied flow can be tested.
• The restore and forward-only upgrade procedures have named owners.

Continue with the control-plane installation or use the Quickstart for a compact evaluation path.