Skip to content
The Gateway

Quick start

This guide assumes you’ve completed installation and the setup wizard. We’ll add a WireGuard tunnel, define a routing policy, register a device, and watch traffic exit through the tunnel.

What we’ll build

Section titled “What we’ll build”
   Laptop (192.0.2.50)
        │
        ▼
   Gateway (10.10.0.1)
        │
   wg0 tunnel
        ▼
   VPN provider exit

The laptop’s traffic — and only that laptop’s — will be policy-routed through wg0. Other LAN devices keep their direct egress.

1. Add a WireGuard tunnel

Section titled “1. Add a WireGuard tunnel”

  1. Open Tunnels in the sidebar.

  2. Click Add tunnel → choose wireguard.

  3. Paste a config you got from your VPN provider:

    [Interface]
    PrivateKey = REDACTED_PRIVATE_KEY=
    Address    = 10.10.0.2/32
    DNS        = 10.10.0.1
    

    [Peer]
    PublicKey  = REDACTED_PUBLIC_KEY=
    Endpoint   = vpn.example.invalid:51820
    AllowedIPs = 0.0.0.0/0
    PersistentKeepalive = 25

  4. Name it wg0 and click Save.

  5. Toggle the tunnel Up.

The tunnel should show Up with a non-zero handshake age within a few seconds. If it doesn’t, check journalctl -u gatewayd -f for handshake errors.

2. Register the device

Section titled “2. Register the device”

The policy engine routes traffic per device, not per IP, because IPs change. Devices are matched by MAC.

  1. Open Devices → Add device.
  2. Fill in:
    • MAC: aa:bb:cc:11:22:33
    • Hostname: laptop-quickstart
    • Trust class: operator (default)
    • Privacy class: balanced
  3. Save.

The device will appear with a green dot once The Gateway sees ARP / DHCP traffic from it.

3. Create a routing policy

Section titled “3. Create a routing policy”
  1. Open Routing policies → New policy.
  2. Match: Device == laptop-quickstart.
  3. Action: Route via tunnel wg0.
  4. Fail policy: fail-closed (the kill-switch engages if wg0 goes down).
  5. Priority: leave default.
  6. Save & Apply.

Behind the scenes The Gateway compiles the policy into:

  • an entry in the split-mark nftables chain that tags packets from the device’s MAC with an fwmark
  • an ip rule fwmark 0xNNN lookup TTTT
  • a route in table TTTT pointing to wg0
  • a kill-switch rule that drops these marked packets when wg0 is down

4. Verify

Section titled “4. Verify”

From the laptop:

Terminal window
curl https://ifconfig.me
# → 198.51.100.42   (the VPN exit, not your ISP)

From the gateway:

Terminal window
gwctl evaluate laptop-quickstart
# Resolved policy:
#   match  : device=laptop-quickstart
#   action : route via tunnel=wg0
#   fwmark : 0x101
#   table  : 1001
#   fail   : closed

In the web UI, Dashboard → Live traffic should show non-zero RX/TX on wg0.

5. Test the kill-switch

Section titled “5. Test the kill-switch”

Bring the tunnel down on purpose:

Terminal window
gwctl tunnels down wg0

From the laptop:

Terminal window
curl --max-time 5 https://ifconfig.me
# → curl: (28) Connection timed out

The laptop has no internet. Other devices on the LAN are unaffected — the kill-switch is per-policy, not global.

Bring it back:

Terminal window
gwctl tunnels up wg0

Traffic resumes within ~1 second of the first WireGuard handshake.

Section titled “Related”
  • Concepts — the vocabulary every command above uses.
  • Recipes → Routing — more policy shapes than the single tunnel here.
  • Use cases — five end-to-end deployments built on these primitives.
  • Troubleshooting — what to check if any of the verification steps misbehaved.