Getting Started
1. Introduction & Core concepts
GateControl is a self-hosted admin tool that combines three components:
- WireGuard for the VPN tunnel. Each connected endpoint is a peer
with its own IP in the VPN subnet (default
10.8.0.0/24). - Caddy as a reverse proxy with automatic Let's Encrypt. Domains are mapped to backends behind the tunnel via so-called routes.
- Node.js admin server with SQLite database. Provides the web UI and the JSON-HTTP API, synchronizes WireGuard state and pushes the Caddy config at runtime via the admin API.
The whole thing runs in a single Docker container with network_mode: host,
orchestrated via supervisord.
Optional additional components
- Home-Gateway — a small companion container that you run in your home network (NAS, Raspberry Pi, mini PC). It establishes the WireGuard tunnel outbound to the server, so that you don't need port forwarding in your home router. The server routes HTTP and L4 traffic through the tunnel up to the gateway, which forwards it locally into the LAN. See Home-Gateway.
- Desktop/mobile client — the official GateControl client (Windows, Android, iOS) is a convenient wrapper around a WireGuard peer plus service browser, RDP launcher and auto-update. Regular WireGuard clients work just as well.
- Internal DNS — built-in dnsmasq that resolves peers by hostname
within the VPN subnet (
nas.vpn.example.com → 10.8.0.12). Optional, license-gated. See Domains & DNS.
Terms
| Term | Meaning |
|---|---|
| Peer | WireGuard endpoint. Either a regular client (laptop, phone, NAS) or a home gateway. |
| Gateway or Gateway-Peer | Special peer type (peer_type=gateway). Gateways see routes and are allowed to forward LAN targets. |
| Route | A domain/port entry in the Caddy config. Mapped to a peer or a gateway. |
| Target-Kind | The target of a route. peer = directly to the WG IP of the peer, gateway = through the gateway into the LAN. |
| Route type | http (Layer 7, with TLS termination), l4 (raw TCP/UDP), rdp (own wizard, produces L4/gateway route plus credential vault). |
| Hostname source | Where the internal hostname of a peer comes from: admin (web UI) or agent (reported by client heartbeat). |
2. Getting started
2.1 Login
You reach the admin UI at the domain configured in GC_BASE_URL.
After the first start there is an admin user with the password set in
setup. Open / → log in with admin and the password.
After login you land on the Dashboard with tiles for connected
peers, active routes, today's traffic, average latency and the
Availability card (shows aggregated how many monitored routes are
currently reachable — clickable to /routes).
2.2 Change admin password
Click your username in the top right → Profile → Change password. If password complexity is enabled under Settings → Security, minimum length, upper/lower/special characters are enforced.
2.3 Create the first peer
To do something useful, you need at least one peer:
- Sidebar → Peers & Clients
- Top right + Add
- Assign a name (e.g.
laptop-mario). The name may only be alphanumeric plus hyphen and must be unique. - Optional: Description, Group, Tags, Expiration date.
- Leave Home Gateway off for a regular client — more on that later.
- Create
The server automatically generates a private WireGuard key, a pre-shared key and the next free IP. Afterward you get a config as a download or QR code. You import the config into the WireGuard app on the device.
2.4 Create the first route
- Sidebar → Domains & Routes
- + Add route — opens the 6-step wizard
- Click through: Target (peer + port) → Transport (enforce HTTPS) → Auth (none) → Access → Reliability → Overview → Save & Caddy reload
If the domain points to your server via DNS, Caddy immediately requests a Let's Encrypt certificate in the background.