Turn any server into a looking-glass location

The BGP Glass agent is a single, outbound-only static binary. Install it on a server to turn that server into a queryable looking-glass location — its output streams back to your pages over an encrypted channel. The agent opens no inbound port (except the optional iperf3 server) and runs with least privilege.

Fastest path

Register a node in your portal, then run the one-command installer it shows you — it downloads the binary, installs a hardened systemd service, and connects:

curl -fsSL https://bgpglass.com/agent/install.sh | sudo bash -s -- \
  --control-plane wss://gw.bgpglass.com \
  --node-key <node-key> \
  --token <token> \
  --download-base https://bgpglass.com/agent

Prefer to build from source or run it your own way? Follow the manual steps below.

1. Register the node

In /admin, create a node and copy its key and the one-time agent token (the token is shown once and stored hashed — keep it safe).

2. Install the binary

Build a static binary (no runtime, no CGO) and copy it to the node:

cd agent && make build          # -> bin/looking-glass-agent (CGO_ENABLED=0)
scp bin/looking-glass-agent root@your-node:/usr/local/bin/

3. Configure

The agent is configured entirely from the environment.

Required

LG_CONTROL_PLANE_URL=wss://gw.bgpglass.com

Control-plane agent endpoint (the gateway, dialed verbatim)

LG_NODE_KEY=frankfurt

This node's key (matches the node you registered)

LG_AGENT_TOKEN=<token>

The plaintext token shown once at registration

Optional

Variable	Default	Description
LG_LOG_LEVEL	info	debug / info / warn / error
LG_COMMAND_TIMEOUT	30s	Per-command timeout
LG_MAX_CONCURRENT	4	Concurrent commands on this node
LG_MAX_OUTPUT_BYTES	1048576	Per-command output cap
LG_IPERF3_ENABLED	false	Host an iperf3 speed-test server (see §5)
LG_IPERF3_PORT	5201	Port the iperf3 server listens on

4. Run it (systemd)

Run as a dedicated unprivileged user with least privilege:

# /etc/systemd/system/looking-glass-agent.service
[Service]
User=lgagent
EnvironmentFile=/etc/looking-glass-agent/agent.env   # chmod 600
ExecStart=/usr/local/bin/looking-glass-agent
Restart=always
AmbientCapabilities=CAP_NET_RAW                       # ICMP for ping/traceroute
ProtectSystem=strict
RestrictAddressFamilies=AF_INET AF_INET6

# then
systemctl enable --now looking-glass-agent

5. iperf3 speed-test server

BGP Glass never runs iperf3 against arbitrary targets. Instead, a node can host an iperf3 server that your visitors connect to. To offer it:

Start the agent with LG_IPERF3_ENABLED=true (and a LG_IPERF3_PORT). The agent supervises the iperf3 -s server and restarts it if it crashes.
Open that TCP port in the node's firewall (it is the only inbound port).
Set the node's iperf3 host and port in /admin so the connect command is shown.
Enable the iperf3 feature on the account's plan.

Visitors then get copyable download / upload / parallel commands, e.g. iperf3 -c <host> -p <port> -R.

Prerequisites & security

Install the tools on PATH: mtr (+ mtr-packet), traceroute, iputils (ping), and iperf3 (only if you enable the server).
Commands are argv-only (never a shell) and targets are screened — private, reserved, loopback, link-local and cloud-metadata ranges are rejected on both the control plane and the agent.
The agent dials out only; it accepts no inbound control connections and holds only CAP_NET_RAW.

Ready to add your first node?

Get started free API reference