BBline-X

Architecture

Bline-X separates a lightweight control plane that coordinates peers from the data path that carries your traffic. The control plane never sees plaintext — all peer-to-peer traffic is encrypted end-to-end by WireGuard.

The big picture

                        ┌──────────────────────────────┐
                        │        CONTROL PLANE         │
   ┌────────────┐  gRPC │  ┌────────────┐  ┌────────┐  │
   │  blinex-   │◄──────┼──┤ management │  │ relay  │  │
   │  agent A   │ :50051│  │:50051/:8080│  │ :3478  │  │
   │            │       │  └────────────┘  └────────┘  │
   │            │       │  ┌────────────────────────┐  │
   │            │◄──────┼──┤  signal :10000         │  │
   │            │ ICE + │  │  ICE signaling +       │  │
   └─────┬──────┘ relay │  │  WireGuard packet relay│  │
         │              │  └───────────┬────────────┘  │
         │              └──────────────┼───────────────┘
         │  WireGuard (encrypted)      │
         │  relayed via signal  .......│..... or DIRECT p2p
         │                             │      (after probe)
   ┌─────▼──────┐                ┌─────▼──────┐
   │  blinex-   │◄──────────────►│  blinex-   │
   │  agent B   │  WireGuard p2p │  agent C   │
   └────────────┘                └────────────┘

Control plane

Three services make up the control plane. They coordinate the mesh but never decrypt your traffic.

  • management — the source of truth. Exposes gRPC on :50051 (agent sync) and HTTPS on :8080 (REST API and dashboard backend). Stores peers, tags, ACLs, and setup keys in PostgreSQL (production) or an in-memory store (development). Issues JWTs to enrolled agents.
  • signal — gRPC on :10000. Performs two jobs: ICE signaling (routing offers, answers, and ICE candidates between agents so they can attempt a direct path) and DERP-style WireGuard packet relay (forwarding encrypted WireGuard packets between peers that cannot reach each other directly).
  • relay — STUN/TURN on :3478. Provides STUN reflexive-address discovery and TURN relaying to assist agents in establishing a direct peer-to-peer path.

Data path

This is the part that makes Bline-X work behind any NAT.

  • Relay by default. Out of the box, WireGuard packets between two peers are relayed through the signal server. This requires no port forwarding and works behind any NAT. Crucially, the packets are always end-to-end encrypted by WireGuard — the signal server only ever sees ciphertext and cannot read your traffic.
  • Direct path in parallel. At the same time, the agent runs ICE (using STUN and TURN from the relay) to discover a direct peer-to-peer path between the two agents.
  • Probe before switching. When ICE finds a candidate direct path, the agent does not blindly trust it. It sends a probe across the new path and only switches the WireGuard traffic over after the probe confirms the path actually passes traffic.
  • Auto-revert. If a direct path later degrades or stops working, the agent automatically reverts to relaying through signal. Connectivity is never sacrificed for the optimization.

The agent

The blinex-agent is a single userspace binary built on wireguard-go. It does not use kernel WireGuard, so the ICE path and the WireGuard path are one and the same.

  • WireGuard device. Runs a wireguard-go userspace device, attached either to a kernel TUN interface blinex0 or to an in-process netstack (userspace networking) when no TUN device is available.
  • RelayBind. A custom conn.Bind implementation that chooses, per peer, whether WireGuard traffic flows over the relay or the direct ICE-established path — and swaps between them transparently as paths come and go.
  • Magic DNS. A built-in DNS server on 127.0.0.1:53535 resolves *.blinex names to peer mesh IPs and forwards everything else upstream. See Magic DNS.
  • Subnet & exit-node routing. Using netlink and iptables MASQUERADE, the agent can advertise routes to local subnets or act as an exit node for other peers.
  • Mesh route. In kernel-TUN mode the agent adds a 100.64.0.0/10 route pointing at blinex0 so the whole mesh address range is reachable.
  • Local control socket. The agent listens on a local control socket that the status CLI (blinex-agent status, peers, routes, version) queries.

Persistent control-plane TLS

The control plane terminates TLS with a self-signed certificate that is persisted to disk (TLS_STATE_DIR, typically a Docker volume). Because the certificate survives container restarts and rebuilds, agents see a stable trust-on-first-use (TOFU) fingerprint — restarting or upgrading the control plane no longer trips a certificate-changed error on every agent.

Authentication

  • An agent enrolls with a setup key and receives a JWT containing its peer ID, WireGuard public key, and account ID.
  • The REST API requires Authorization: Bearer <jwt>.
  • The gRPC sync stream authenticates with the WireGuard public key directly — the key itself proves identity.