WireGuard Config Builder

Define your WireGuard mesh network in YAML, get production-ready configs

Transform a simple network topology definition into complete WireGuard configurations with automatic key management, routing rules, and NAT or routed forwarding setup.

What It Does

You define who needs to connect to what in a YAML file. The tool generates:

• Complete WireGuard config files for each host
• Cryptographic keypairs and preshared keys (stored and reused)
• iptables rules for NAT or routed forwarding on gateway hosts
• Proper peer relationships so traffic flows both ways

Common Use Cases

• Remote access VPN - Developers connect to office/cloud networks from anywhere
• Multi-region access - Route traffic to different cloud regions through separate gateways
• Site-to-site VPN - Connect office networks together
• Kubernetes access - Secure access to cluster services and pods
• Split-tunnel setups - Route only specific networks through VPN, not all traffic
• High availability - Multiple gateways for redundancy and failover

Quick Start

1. Install

go install github.com/juanmarin-co/wg-config-builder/cmd/wg-config-builder@latest

2. Define your network

Create my-network.yaml:

name: my-network
hosts:
  # Gateway server with a public IP
  - name: gateway
    endpoint: 203.0.113.10:51820
    egressInterface: eth0
    interface:
      address: 10.200.0.1/32
      mtu: 1380

  # Your laptop
  - name: laptop
    interface:
      address: 10.200.0.10/32
      mtu: 1380
      dns:
        - 8.8.8.8

routes:
  # Laptop connects to gateway to reach private networks
  - from: laptop
    to: gateway
    persistentKeepalive: 25
    allowedIps:
      - 10.1.0.0/16  # Private network behind gateway

3. Generate configs

wg-config-builder -config my-network.yaml

This creates generated/my-network/gateway.conf and generated/my-network/laptop.conf.

4. Deploy and start

# On gateway server
scp generated/my-network/gateway.conf root@gateway:/etc/wireguard/wg0.conf
ssh root@gateway "wg-quick up wg0"

# On laptop
sudo cp generated/my-network/laptop.conf /etc/wireguard/wg0.conf
sudo wg-quick up wg0

Understanding Routes

A route defines one direction of connectivity:

- from: laptop
  to: gateway
  allowedIps:
    - 10.1.0.0/16

This means: "Laptop should be able to reach 10.1.0.0/16 by going through gateway."

The tool automatically creates the peer relationship on both sides:

• Laptop's config gets gateway as a peer
• Gateway's config gets laptop as a peer

About allowedIps:

• These are networks/IPs reachable through the peer
• allowedIps is required and every entry must use explicit canonical CIDR notation
• Traffic to these addresses will be sent through the WireGuard tunnel
• It does NOT automatically include the peer's own IP
• Add the peer's WireGuard IP explicitly (for example 10.200.0.1/32) if you need direct access to that host itself

Configuration Reference

Host Types

Gateway/Bastion (has public IP, routes traffic):

- name: gateway
  endpoint: 203.0.113.10:51820     # Public IP:port
  egressInterface: eth0             # Interface used for transit forwarding
  interface:
    address: 10.200.0.1/32          # WireGuard tunnel IP (/32 for IPv4, /128 for IPv6)
    mtu: 1380                        # Optional explicit interface MTU

Client (connects to gateways):

- name: client
  interface:
    address: 10.200.0.10/32         # WireGuard tunnel IP
    mtu: 1380                       # Optional explicit interface MTU
    dns:                            # Optional DNS servers
      - 8.8.8.8

When mtu is omitted, wg-quick selects it automatically on each host. Set it explicitly when every peer must use an MTU supported by the smallest underlay path.

Route Fields

- from: client              # Source host
  to: gateway               # Destination host
  mode: nat                 # Optional: nat (default) or routed
  persistentKeepalive: 25   # Optional: keep connection alive (for NATed clients)
  allowedIps:               # Required explicit canonical CIDRs reachable through this route
    - 10.0.0.0/8

NAT vs Routed Mode

• mode: nat (default) adds route-scoped MASQUERADE rules on the gateway.
• mode: routed forwards traffic without NAT. The upstream/private network must route the WireGuard client CIDRs back via the gateway.
• Transit routes require the to host to define egressInterface.
• IPv6 direct peer access is supported, but IPv6 transit forwarding is not generated yet.

What Gets Generated

For each host, you get a complete WireGuard config:

Gateway config includes:

• WireGuard interface setup
• Private key (auto-generated)
• Listen port from endpoint
• iptables rules for NAT or routed forwarding
• Peer sections for each client

Client config includes:

• WireGuard interface setup
• Private key (auto-generated)
• DNS servers
• Peer sections with gateway endpoints

All keys are stored in keystore.json and reused on subsequent runs.

Command Line Options

wg-config-builder [options]

Options:
  -config string
        Path to the configuration file (default "config.json")
  -keystore string
        Path to the keystore file (default "keystore.json")
  -output string
        Directory to output the generated configurations (default "generated")

Requirements

• Go 1.21 or later
• WireGuard tools on deployment hosts (wg-quick)

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Write tests for your changes
4. Use Conventional Commits
5. Open a Pull Request

License

MIT License - see LICENSE file for details

---

Questions? Check config.example.yaml for more examples or open an issue.