Self-host a node

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.

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://bgpglass.com/agent

Control-plane agent endpoint

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

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:

  1. 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.
  2. Open that TCP port in the node's firewall (it is the only inbound port).
  3. Set the node's iperf3 host and port in /admin so the connect command is shown.
  4. 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

API reference → Get started