Agent — Installation & Usage

The blinex-agent is the single binary that runs on every device in your mesh. It builds the WireGuard tunnels, runs Magic DNS, and exposes a local status CLI. This page covers installation on all platforms, configuration, the status CLI, and running inside LXC containers.

Installation

One-line install (Linux)

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

This downloads the appropriate binary and installs a systemd service.

Pre-built binaries

Binaries for every supported platform are published on the DJR-FP/blinex-agent releases page:

• Linux — amd64 and arm64 (kernel TUN with netstack fallback).
• Windows — amd64 (netstack).
• macOS — amd64 and arm64 (netstack).

# Linux amd64 example
curl -fsSL -o blinex-agent \
  https://github.com/DJR-FP/blinex-agent/releases/latest/download/blinex-agent-linux-amd64
chmod +x blinex-agent
sudo mv blinex-agent /usr/local/bin/

Configuration file

The agent reads /etc/blinex/agent.json. Flags and environment variables override file values.

{
  "management_url": "https://your-host:8080",
  "signal_url": "your-host:10000",
  "setup_key": "BLINEX-DEFAULT-KEY",
  "turn_user": "blinex",
  "turn_pass": "your-relay-auth-pass",
  "tls_skip_verify": false
}

Flags and environment variables

Kernel TUN vs netstack modes

The agent runs in one of two networking modes:

• Kernel TUN mode (Linux, with /dev/net/tun). The agent creates a real blinex0 interface. Mesh traffic is fully routable by the host kernel, so applications on the host — and subnet/exit-node routing — work without any extra configuration. This is the default on Linux.
• Netstack mode(Windows, macOS, and Linux without a TUN device). The agent runs a userspace network stack inside the process. Inbound connections to this device work, but traffic originated by other host applications does not transparently enter the mesh (the same trade-off as Tailscale's userspace mode).

Status CLI

The running agent exposes a local control socket at /var/run/blinex-agent.sock. The CLI subcommands query it — they talk to the running daemon, they do not start a second agent.

blinex-agent status

Shows a one-screen summary of the agent's state.

$ blinex-agent status
Bline-X agent v0.12.2
Mesh IP:    100.64.0.1
Interface:  blinex0 (kernel TUN)
Peers:      4 connected
Routes:     2 advertised

Reports the agent version, this device's mesh IP, the interface name and mode (kernel TUN or netstack), the connected peer count, and the advertised route count.

blinex-agent peers

Lists every peer and how this agent is reaching it.

$ blinex-agent peers
HOSTNAME     MESH IP       DNS NAME            PATH
server-2     100.64.0.2    server-2.blinex     direct
server-3     100.64.0.3    server-3.blinex     relay
laptop-jane  100.64.0.7    laptop-jane.blinex  direct
db-1         100.64.0.9    db-1.blinex         relay

The PATH column shows whether traffic to that peer is flowing over a direct peer-to-peer path or is being relayed through the signal server.

blinex-agent routes

Lists the subnet and exit-node routes this agent advertises, along with the gateway.

$ blinex-agent routes
ROUTE             TYPE        GATEWAY
192.168.10.0/24   subnet      100.64.0.1
0.0.0.0/0         exit-node   100.64.0.1

blinex-agent version

$ blinex-agent version
blinex-agent v0.12.2

Running in LXC containers

Unprivileged LXC containers do not expose /dev/net/tun, so the agent falls back to netstack mode — inbound connections work, but traffic from other apps on the container host will not transparently route into the mesh.

To get full kernel-TUN mode, pass the TUN device through from the Proxmox host. Add the following to the container's config (/etc/pve/lxc/<CTID>.conf):

lxc.cgroup2.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file

Then restart the container:

pct restart <CTID>

After the restart the agent finds /dev/net/tun and creates the blinex0 interface in full kernel-TUN mode.

Uninstall

Linux

sudo systemctl stop blinex-agent
sudo systemctl disable blinex-agent
sudo rm /etc/systemd/system/blinex-agent.service
sudo rm /usr/local/bin/blinex-agent
sudo rm -rf /etc/blinex /var/lib/blinex

Windows

sc.exe stop blinex-agent
sc.exe delete blinex-agent
del "C:\Program Files\Blinex\blinex-agent.exe"

macOS

sudo launchctl unload /Library/LaunchDaemons/co.blinex.agent.plist
sudo rm /Library/LaunchDaemons/co.blinex.agent.plist
sudo rm /usr/local/bin/blinex-agent