Network Architecture

Airdress routes traffic from the public internet to services running on your local machine through a global anycast network. There are no port-forwarding rules to configure, no dynamic DNS to maintain, and no VPN concentrators to manage. Your operator establishes an outbound WireGuard tunnel; the Airdress relay network handles the rest.

Architecture overview

flowchart LR
    Client([Client]) --> DNS[DNS PoP]
    Client --> Relay[Relay PoP]
    Relay -->|WireGuard tunnel| Operator[Operator]
    Operator --> Service([Local Service])

    style DNS fill:#2563eb,color:#fff
    style Relay fill:#059669,color:#fff
    style Operator fill:#7c3aed,color:#fff

Clients resolve your airdress name through anycast DNS, then connect to the nearest relay PoP over the same anycast prefix. The relay forwards traffic through a WireGuard tunnel to your operator, which delivers it to your local service.

Anycast and BGP

Airdress operates its own autonomous system and announces a dedicated IP prefix from every point of presence. Anycast routing means that when a client connects, the internet’s BGP routing tables direct the packets to the geographically nearest PoP.

If a PoP becomes unhealthy, its BGP route is automatically withdrawn and traffic shifts to the next-nearest PoP within seconds.

Key properties of this design:

• Automatic failover. No DNS TTL propagation delay — BGP convergence handles it.
• Geographic affinity. Clients reach the closest PoP by default, minimizing latency.
• Single IP address. All PoPs announce the same prefix, so DNS records never change.

For the current list of IP prefixes, see airdress.co/ips (plain text) or airdress.co/ips.json (machine-readable). Network details are published at airdress.co/network.

Relay PoPs

Relay PoPs accept client traffic and forward it to operators through WireGuard tunnels. The relay handles:

• HTTP (port 80) — the relay inspects the Host header to determine the destination operator.
• HTTPS/TLS (port 443) — TLS passthrough mode. The relay reads the SNI (Server Name Indication) to route the connection. Your operator terminates TLS, so end-to-end encryption is preserved.
• WireGuard — tunnel transport between relay and operator.

Current locations

PoP	City	Region
EWR	Newark, NJ	US East
AMS	Amsterdam	Europe

Additional locations are planned.

Health and failover

Each PoP is continuously health-checked. When the relay process becomes unhealthy, the PoP’s BGP route is withdrawn and traffic automatically shifts to the next-nearest healthy PoP. When the relay recovers, the route is re-announced.

PoPs are deployed as immutable images. Updates are rolled out one PoP at a time with health verification gates between each.

DNS PoPs

DNS PoPs provide authoritative DNS for airdress names. When you claim an airdress name, a DNS record is created that points to the relay.

Key capabilities:

• In-memory cache — zone data is cached in memory for fast lookups.
• Near-instant propagation — record changes propagate to all PoPs and invalidate the cache within seconds.
• Response Rate Limiting (RRL) — mitigates DNS amplification attacks.
• DNSSEC — online signing ensures all responses are cryptographically verifiable.

DNS PoPs run on separate machines from relay PoPs at the same locations.

Traffic flow

A complete request from a client to your local service follows this path:

sequenceDiagram
    participant C as Client
    participant D as DNS PoP
    participant R as Relay PoP
    participant O as Operator
    participant S as Local Service

    C->>D: 1. Resolve myapp.a.airdr.es
    D-->>C: 2. A record (relay VIP)
    C->>R: 3. Connect to relay (nearest PoP)
    R->>R: 4. Extract Host header / SNI
    R->>O: 5. Forward via WireGuard tunnel
    O->>S: 6. Deliver to local service
    S-->>O: Response
    O-->>R: Response (WireGuard)
    R-->>C: Response

Step by step:

1. DNS resolution. The client resolves your airdress name. The query reaches the nearest DNS PoP via anycast.
2. Relay VIP returned. The DNS PoP returns an A record pointing to the relay anycast VIP.
3. Client connects to relay. The client opens an HTTP or TLS connection. BGP routing delivers the packets to the geographically nearest relay PoP.
4. Host/SNI extraction. The relay inspects the Host header (HTTP) or SNI (TLS) to identify which operator should receive this traffic.
5. WireGuard forwarding. The relay forwards the traffic through the WireGuard tunnel to the correct operator. The tunnel is established outbound by the operator, so no inbound ports need to be open on your machine.
6. Local delivery. The operator’s reverse proxy delivers the request to your local service on the configured port.

Tip

The WireGuard tunnel is established outbound from your operator to the relay. This means Airdress works behind NATs, firewalls, and CGNAT without any port-forwarding configuration.

The operator

The operator is the component that runs on your machine. It is a single binary (airdress-operator) that bundles several subsystems:

Subsystem	Purpose
WireGuard	Maintains the tunnel to the nearest relay PoP
Reverse proxy	Routes incoming requests to local services
DNS server	Authoritative DNS for the operator’s own records
Embedded database	Local data store; can be replaced with an external database via database.url
App runtime	Hosts plugins and mini-apps
Chat	End-to-end encrypted messaging
Ingress	Receives webhooks and events (SSE, WebSocket, CloudEvents)
Enrollment	Claims and manages airdress names
Federation	Connects operators to each other

The operator is designed to be self-contained. A default installation requires no external dependencies.

Security model

Traffic between the relay and your operator is always encrypted:

• WireGuard encryption. All traffic between the relay PoP and your operator passes through a WireGuard tunnel with authenticated encryption (Curve25519, ChaCha20-Poly1305).
• TLS passthrough. For HTTPS traffic, the relay does not terminate TLS. Your operator holds the certificate and private key. The relay sees only the SNI for routing — it cannot read the request body, headers, or response.
• DNSSEC. All DNS responses are signed, preventing spoofing and cache poisoning.
• Immutable infrastructure. PoPs are deployed as read-only images. There is no configuration drift — updates ship as new images.

Note

Airdress never sees the plaintext content of your HTTPS traffic. The relay operates as a pass-through; TLS termination happens exclusively on your operator.

Protocol Support Detailed reference for all supported transport and application protocols.