Edge Gateway (WireGuard + Traefik + Proxy Agent)

Edge gateway that joins a WireGuard controller, runs Traefik on the host network, and exposes an agent API for dynamically creating:

• HTTPS host-based routes via Traefik dynamic config files
• TCP port forwards via iptables DNAT across the WireGuard network

Designed to be the public entrypoint for your private WG mesh.

---

Components

edge-net

WireGuard client container that:

• generates/persists WG keypair
• joins controller via /join
• writes /etc/wireguard/wg0.conf
• brings up wg0 on the host network (network_mode: host)
• stays alive (sleep infinity)
• provides healthcheck: wg show wg0

traefik

Traefik reverse proxy:

• runs on host network
• listens on :80 and :443
• watches /etc/traefik/dynamic for routes (file provider)

proxy-agent

FastAPI service that:

• writes Traefik dynamic YAML files (/http/routes)
• manages TCP DNAT forwards via iptables (/tcp/forwards)
• persists state in /data/state.json
• restores iptables rules on startup

---

Architecture

                Internet
                  │
            (80/443 + TCP ports)
                  │
            ┌───────────────┐
            │     Traefik     │  (host network)
            └───────┬────────┘
                    │ dynamic config (*.yml)
            ┌───────▼────────┐
            │   Proxy Agent   │  (FastAPI)
            │  - http routes  │
            │  - tcp forwards │
            └───────┬────────┘
                    │ DNAT / WG forwarding
            ┌───────▼────────┐
            │   WireGuard wg0  │  (edge-net)
            └───────┬────────┘
                    │ WG mesh (10.50.0.0/24)
           ┌────────▼─────────┐
           │ nodes / services  │
           └───────────────────┘

---

Features

• Auto-join WG controller on startup (idempotent)
• Traefik dynamic routing via file provider
• Create/remove HTTPS host routes via API
• Create/remove TCP port forwards via API
• Persistent state for routes/forwards
• Automatic restore of iptables rules after restart
• Runs fully with Docker Compose + network_mode: host

---

Requirements

Host:

• Linux with kernel WireGuard support
• iptables available (iptables-nft or legacy both ok if consistent)
• Docker / docker compose
• cap_add: NET_ADMIN and SYS_MODULE needed for wg/iptables in containers
• /lib/modules mounted read-only for wg kernel module usage

---

Running

1) Configure .env

Minimal required:

CONTROLLER_URL=http://<controller_public_ip>:9000
JOIN_TOKEN=<join_token>
NODE_ID=edge-gateway-1

AGENT_TOKEN=<optional_token>

# Traefik DNS / ACME values are up to your setup
EDGE_AGENT_PORT=8081

2) Start

docker compose up -d --build

3) Check health

docker ps
docker logs edge-net
docker logs edge-agent

---

Volumes / Persistence

• ./wireguard:/etc/wireguard Stores generated wg0.conf (and related files if you place them there)

• ./agent-data:/data Stores:

  • join.json from controller
  • state.json for proxy-agent (routes + forwards)

• ./traefik/dynamic:/etc/traefik/dynamic Dynamic Traefik config files (*.yml) generated by the agent

• ./traefik/acme:/acme ACME storage (if you use cert resolvers that need it)

---

Environment Variables

edge-net

Variable	Description
CONTROLLER_URL	Controller API base URL
JOIN_TOKEN	Join token (sent as X-Join-Token)
NODE_ID	Node id used in controller peers
WG_IFACE	WG interface name (default: wg0)
DATA_DIR	Persistent dir (default: /data)

proxy-agent

Variable	Description
AGENT_TOKEN	Optional auth token for agent API
TRAEFIK_DYNAMIC_DIR	Directory for Traefik dynamic YAML
STATE_FILE	Persistent state file
WG_IFACE	WG interface used for masquerade (wg0)
TRAEFIK_ENTRYPOINT	EntryPoint name (default: websecure)
TRAEFIK_CERTRESOLVER	Cert resolver name

---

API (Proxy Agent)

Base URL (host network): http://127.0.0.1:8081 (or your host IP)

Auth header (if enabled):

• X-Agent-Token: <AGENT_TOKEN>

NOTE: In your code require_token() is currently “pass”-ed (auth disabled). If you want auth: uncomment the HTTPException lines.

---

Health

GET /health

---

HTTP Routing (Traefik)

Create HTTPS host route

POST /http/routes
Content-Type: application/json

Body:

{
  "route_id": "vm-123",
  "hostname": "vm-123.service.com",
  "target_url": "http://10.50.0.12:8080",
  "entrypoint": "websecure",
  "certresolver": "dnsresolver"
}

What it does:

• writes /etc/traefik/dynamic/<route_id>.yml
• Traefik picks it up automatically

List routes

GET /http/routes

Delete route

DELETE /http/routes/{route_id}

---

TCP Forwarding (iptables DNAT)

Create forward

POST /tcp/forwards
Content-Type: application/json

Body:

{
  "forward_id": "vm-123-ssh",
  "public_port": 22015,
  "target_ip": "10.50.0.12",
  "target_port": 32215,
  "proto": "tcp"
}

What it does:

• nat/PREROUTING DNAT: public_port → target_ip:target_port
• filter/FORWARD ACCEPT rule
• ensures net.ipv4.ip_forward=1
• ensures MASQUERADE -o wg0 exists (critical for reply path)
• persists into /data/state.json

List forwards

GET /tcp/forwards

Delete forward

DELETE /tcp/forwards/{forward_id}

Also attempts to cleanup wg masquerade if no forwards remain.

---

Startup Restore

On agent startup:

• reads /data/state.json
• re-applies TCP forwards (DNAT + FORWARD + wg0 MASQUERADE)
• re-adds established/related conntrack accept rule

HTTP routes are restored implicitly because YAML files live in TRAEFIK_DYNAMIC_DIR.

---

Security Notes

• network_mode: host means containers share host network namespace.
• TCP forwarding + routing are powerful: lock down access properly.
• If you expose agent API beyond localhost, enable token auth and firewall it.
• Consider restricting inbound ports and using allowlists.

---

Troubleshooting

WireGuard is up but traffic doesn’t return

Make sure wg masquerade exists on the edge host:

iptables -t nat -S POSTROUTING | grep wg0

You should see something like:

-A POSTROUTING -o wg0 -j MASQUERADE

Traefik doesn’t see routes

Check if YAML file is written:

ls -la ./traefik/dynamic
docker logs edge-traefik

Agent rules not applied after restart

Check state:

cat ./agent-data/state.json
docker logs edge-agent