Your First Tunnel

In this guide you will start a local web server, expose it through an Airdress anycast relay, inspect the tunnel, and shut it down cleanly. Plan about fifteen minutes.

What you will build

A publicly reachable tunnel from a service running on your machine, through a WireGuard connection to an Airdress relay PoP, out to the internet over anycast BGP. You will see the full path traffic takes and learn how to verify each hop.

Prerequisites

• The airdress-operator binary is installed. If not, complete the Quickstart first.
• A local HTTP server you can start on demand (the example below uses Python, but any server on a known port works).
• An internet connection.

1. Start a local web server

   Open a terminal and start a simple HTTP server on port 8000:

   python3 -m http.server 8000

   Confirm it is responding:

   curl -s http://127.0.0.1:8000/ | head -5

   You should see the HTML directory listing. Leave this terminal running.

2. Start the operator with explicit bind and WireGuard settings

   In a second terminal, start the operator and tell it which address and WireGuard port to use:

   airdress-operator serve --bind 0.0.0.0:8080 --wg-port 51820

   Flag	Purpose
   --bind 0.0.0.0:8080	Address and port the operator’s HTTP listener binds to.
   --wg-port 51820	UDP port for the WireGuard tunnel to the relay PoP.

   The operator connects to the nearest relay PoP, establishes a WireGuard tunnel, and begins accepting forwarded traffic. Log output confirms the connection:

   INFO  wireguard handshake complete  relay=ewr  latency=18ms
   INFO  operator ready  bind=0.0.0.0:8080  wg_port=51820

3. Check the operator status

   In a third terminal, inspect the running operator:

   airdress-operator status

   Example output:

   operator
     state:   running
     bind:    0.0.0.0:8080
     wg_port: 51820
   
   tunnel
     relay:     ewr (Newark)
     endpoint:  185.43.32.11
     handshake: 12s ago
     rx:        1.2 KiB
     tx:        856 B

   The handshake field shows how recently the WireGuard session was confirmed. A value under 120 seconds means the tunnel is active.

4. Verify the health endpoint

   airdress-operator health

   Or with curl:

   curl http://127.0.0.1:8080/healthz

   A healthy response means the operator, its tunnel, and the relay PoP are all functioning.

5. Stop the operator

   Press Ctrl+C in the terminal where airdress-operator serve is running. The operator drains active connections, tears down the WireGuard interface, and exits:

   INFO  shutting down  reason=SIGINT
   INFO  wireguard interface removed
   INFO  operator stopped

   Then stop the Python web server with Ctrl+C as well.

What is happening under the hood

When you run airdress-operator serve, the following chain is set up:

1. The operator creates a WireGuard interface and connects to an Airdress relay PoP (currently Newark or Amsterdam).
2. The relay PoP announces the anycast prefix via BGP. Anycast routing sends each client to the geographically nearest PoP.
3. The Airdress authoritative DNS servers resolve your *.a.airdr.es name to the relay VIP.
4. A client request hits the relay VIP, enters the WireGuard tunnel, and arrives at the operator on your machine, which forwards it to your local service.

The relay never sees your plaintext traffic — WireGuard encrypts the full tunnel. The operator and relay exchange only encrypted UDP packets.

Next steps

Configuration Fine-tune the operator with a TOML config file and environment variables.

Network Architecture Deep dive into BGP anycast, relay PoPs, DNS resolution, and the WireGuard data path.

Deployment Checklist Production readiness checklist for running the operator as a long-lived service.