BBline-X

Quickstart

This guide takes you from nothing to a working Bline-X mesh with two connected peers. You will deploy the control plane with Docker Compose, install the agent, enroll it with a setup key, and verify connectivity.

Prerequisites

  • A host for the control plane with Docker and Docker Compose.
  • One or more machines (Linux, Windows, or macOS) to run the blinex-agent.
  • Inbound UDP 3478 and UDP 49152-49252 open on the control-plane host (for STUN/TURN direct-path assist), plus the management and signal ports below.

1. Deploy the control plane

Clone the repository and start the stack:

git clone https://github.com/DJR-FP/blinex
cd blinex
cp .env.example .env
# edit .env: set JWT_SECRET, POSTGRES_PASSWORD,
#            BLINEX_DEFAULT_KEY, RELAY_AUTH_PASS
docker compose up -d

This brings up four services:

  • management — gRPC :50051 and HTTPS :8080 (peers, tags, ACLs, setup keys).
  • signal — gRPC :10000 (ICE signaling and WireGuard packet relay).
  • relay — STUN/TURN :3478 (direct-path assist).
  • dashboard — the web UI for managing the mesh.

2. Install the agent

On each machine you want on the mesh, run the install script:

curl -fsSL https://get.blinex.co.uk | sh

This installs the blinex-agent binary and a systemd service (on Linux). See the Agent docs for Windows and macOS installation and for installing from pre-built binaries.

3. Enroll the agent

Enroll the agent with a setup key. You can pass configuration via flags or environment variables:

sudo BLINEX_SETUP_KEY=BLINEX-DEFAULT-KEY \
  BLINEX_MANAGEMENT_URL=https://your-host:8080 \
  BLINEX_SIGNAL_URL=your-host:10000 \
  BLINEX_TURN_PASS=your-relay-auth-pass \
  blinex-agent

Enrollment environment variables

VariableDescription
BLINEX_SETUP_KEYEnrollment key. The seeded default is BLINEX-DEFAULT-KEY.
BLINEX_MANAGEMENT_URLHTTPS URL of the management server, e.g. https://your-host:8080.
BLINEX_SIGNAL_URLHost:port of the signal server, e.g. your-host:10000.
BLINEX_TURN_PASSTURN auth password, matching RELAY_AUTH_PASS on the relay.

On success, the agent prints something like Connected to mesh as server-1 (100.64.0.1) and the device appears in the dashboard.

4. Verify connectivity

Enroll a second machine the same way, then ping it by its Magic DNS name:

ping server-2.blinex
# 64 bytes from 100.64.0.2: icmp_seq=1 ttl=64 time=2.1 ms

You can also inspect the local agent state with the status CLI:

blinex-agent status
# Bline-X agent v0.12.2
# Mesh IP:    100.64.0.1
# Interface:  blinex0 (kernel TUN)
# Peers:      1 connected
# Routes:     0 advertised

5. Open the dashboard

Browse to the dashboard served by the control plane. Sign in, and you will see both peers, their mesh IPs, and their connection status. From here you can create real setup keys, assign tags and access policies, and manage devices.

Next steps