Blackhole Architecture

Every Blackhole device runs a WireGuard interface. The coordination server distributes public keys and allowed-IPs so devices can form direct encrypted tunnels. No traffic passes through the coordination server — it is purely a control plane.

Each device receives a stable IP in the 100.64.0.0/10 range (CGNAT space). Addresses are deterministic and tied to the device identity key, so they survive reboots and network changes.

WireGuard provides ChaCha20 stream cipher, Poly1305 MAC, and Curve25519 ECDH for perfect forward secrecy. Keys rotate automatically on a 3-minute interval.

Most devices are behind NAT. Blackhole uses a multi-strategy approach to punch through:

1. 1.STUN endpoint discovery — the client queries Blackhole STUN servers to learn its public IP:port before connecting.
2. 2.Simultaneous hole-punch — both peers send UDP packets simultaneously, opening a NAT mapping on each side. Works against cone NAT.
3. 3.Relay fallback — if hole-punch fails (symmetric NAT, corporate firewalls), traffic is relayed through the nearest DERP-compatible relay server with no configuration required.

Connection success rate is >99% across real-world networks. Direct connections achieve <2ms LAN latency. Relay paths add 10–40ms depending on geographic proximity.

Relay servers are distributed globally. The client automatically selects the lowest-latency relay based on RTT probes sent at startup. Traffic is end-to-end encrypted by WireGuard — relay servers see only opaque UDP datagrams.

On the Business plan you can deploy private relay nodes within your own infrastructure, keeping all traffic on-premises even for devices behind symmetric NAT.

Blackhole ACLs are evaluated per-packet on every device. The coordination server distributes compiled rule sets — no rules require a round-trip to the server at connection time.

Rules follow a tag-based model: you assign tags to devices (e.g. server, dev-laptop) and write rules in terms of tags rather than IPs.

{
  "acls": [
    // Developers can reach all servers
    { "action": "accept", "src": ["tag:dev-laptop"], "dst": ["tag:server:*"] },
    // Servers can only talk to each other
    { "action": "accept", "src": ["tag:server"], "dst": ["tag:server:*"] },
    // Default deny
    { "action": "deny", "src": ["*"], "dst": ["*"] }
  ],
  "tagOwners": {
    "tag:server":     ["autogroup:admin"],
    "tag:dev-laptop": ["autogroup:member"]
  }
}

Every device in your mesh gets a DNS name automatically:[hostname].[tailnet-name].bhnet. No DNS server to run, no /etc/hosts to maintain.

Blackhole injects a DNS resolver into the device's nameserver chain. Queries for .bhnet are answered locally from the distributed key-value store synced by the coordination server. All other queries pass through your normal DNS.

Custom domains are supported — you can map db.internal to any mesh IP, or add a split-DNS override so api.mycompany.com resolves differently inside the mesh vs. the public internet.

Blackhole uses a defense-in-depth approach. No single component being compromised can break the confidentiality of your mesh traffic:

• End-to-end encryption: WireGuard keys are generated on-device and never leave the device. The coordination server distributes public keys only.
• Zero-trust by default: New devices join with no permissions. Admins must explicitly grant access via ACL rules.
• Relay confidentiality: Relay servers handle WireGuard UDP but cannot decrypt the payload. They are infrastructure only.
• Audit logging: Every peer connection, ACL change, and key rotation is logged with timestamps and stored for 90 days.