Installing the software agent

The software agent is the Relayant box's own software, installed on hardware the site already has. It enrols, connects out, finds and monitors devices and reaches them the same way as a box. It does not own or change the network it runs on.

It comes in two forms. The Linux service runs on Debian, Ubuntu or Raspberry Pi OS, on a PC, a server or any Raspberry Pi. The router package runs on a router you own: OpenWrt up to 24.10, or Teltonika RutOS.

The box on a LAN port, the software agent on a PC or Raspberry Pi, or the agent on the router itself.

Before you start

You need a host on the site's wired network: a Linux PC or server, a Raspberry Pi, or the site's own router. Use a cable, not Wi-Fi; many access points hide other devices from a Wi-Fi client. You need root (or sudo) on that host, over SSH or at its keyboard, and outbound internet from it. Nothing is opened on the router. You need the site created in the portal, and an owner or operator sign-in.

The commands below use the portal's own server address, https://app.relayant.net, and a placeholder code, ABCD-EFGH-JKMN-PQRS. The portal prints yours with the code filled in; copy from there.

Get the setup code from the portal

A box has its setup code printed on its label. Software has no label, so the portal issues one.

Open the site in the portal and choose Add a box.
Choose the Install the software agent tab.
Choose Show the install commands. The portal issues a setup code for this site and prints each command with it filled in.
Choose the tab for your host: Linux, or OpenWrt / Teltonika.

Opening the page again shows the same commands until a machine has used the code. Unlike a box's serial number, which is tied to a box you already own, a software code is unassigned until a machine uses it. Treat it like a password until then: it lets a machine join this site.

A code connects once. The first machine to use it holds it; a different machine presenting the same code is refused, and you are emailed. To move the agent to a replacement machine, choose Re-pair on the Boxes page first, then install there.

The Linux service

For Debian, Ubuntu and Raspberry Pi OS, on x86-64, arm64 or 32-bit ARM, so every Raspberry Pi. The host needs systemd, which these all have.

Install

Paste the one line from the Linux tab:

Install the Linux service

curl -fsSL 'https://app.relayant.net/api/downloads/install-relayant-agent.sh' \
  | sudo sh -s -- --server 'https://app.relayant.net' --setup-code 'ABCD-EFGH-JKMN-PQRS'

The installer adds the WireGuard tools with apt, downloads the agent from your Relayant server and checks it against the checksum the server states. It runs the agent once to check it works on this CPU, then installs a service named relayant-agent and starts it.

Check it is running

Status and live log

sudo systemctl status relayant-agent
journalctl -u relayant-agent -f

In the portal, the site's page lists the agent among the boxes as Software agent · Linux, and it searches the site's network. From here, follow Getting started from "Search the site's network".

Upgrade

Updates arrive over the air, signed by us, the same way a box is updated. Running the install command again also upgrades in place and keeps the agent's identity.

Remove

Remove the service

curl -fsSL 'https://app.relayant.net/api/downloads/install-relayant-agent.sh' | sudo sh -s -- --uninstall

--uninstall removes everything but the agent's identity, so reinstalling brings it back as the same agent. --purge removes the identity too. Then remove it from the site in the portal.

The router package

For OpenWrt up to 24.10 and Teltonika RutOS, over SSH as root. Packages are built for four router architectures, which cover the Teltonika range and most routers. The router refuses a package built for a different architecture, so the wrong one is not installed.

Check the router has room

Before choosing this form, check the router has the space:

Flash: about 9 MB free. df -h /overlay shows it. Routers with 16 MB of flash do not have it; the Teltonika RUTX series does, and the RUT241 and RUT950 class does not.
Memory: 128 MB of RAM or more. free shows it.
WireGuard: kmod-wireguard, wireguard-tools and ip-full. opkg list-installed | grep -E 'wireguard|ip-full' shows what is there.

Install

Paste the lines from the OpenWrt / Teltonika tab. They pick the right package for the router's CPU by themselves.

Install the router package

opkg update && opkg install kmod-wireguard wireguard-tools ip-full
ARCH=$(opkg print-architecture | awk '{print $2}' | grep -xE 'mips_24kc|mipsel_24kc|arm_cortex-a7_neon-vfpv4|aarch64_cortex-a53' | tail -n 1)
wget -O /tmp/relayant-agent.ipk "https://app.relayant.net/api/downloads/relayant-agent_$ARCH.ipk"
opkg install /tmp/relayant-agent.ipk
uci set relayant.agent.server='https://app.relayant.net'
uci set relayant.agent.setup_code='ABCD-EFGH-JKMN-PQRS'
uci commit relayant && /etc/init.d/relayant-agent restart

The log is logread -e relayant-agent. The settings live in /etc/config/relayant and are kept across package upgrades. In the portal the agent appears as Software agent · OpenWrt.

What the package changes on your router

What the router package does on a router you own, and what it does not do.
It does	It does not do
Adds its own WireGuard interface, `relayant0`, while running	Change the LAN, WAN, DHCP, DNS, Wi-Fi or any existing interface
Adds one firewall zone of its own, with one rule admitting the relay's connections on that interface	Change any existing firewall zone, rule or forwarding
Reads the router's DHCP leases for device names	Flash firmware, or update itself
Removes its zone when the package is removed	Bind the DHCP port the router's own server needs

The firewall zone is needed because OpenWrt rejects connections on an interface no zone names. To stop even that, set manage_firewall to 0 in /etc/config/relayant before installing; the relay's connections must then be admitted by hand.

Teltonika

Teltonika RutOS is OpenWrt underneath and installs the same package over SSH. The agent uses its own interface, so it runs beside Teltonika RMS and beside any WireGuard VPN already on the router. The Teltonika steps have not yet been checked on a real router; confirm them on the first router of each model before installing at scale.

OpenWrt 25.12 and later

These releases replaced opkg with apk, so opkg install is not available. The same package installs by hand, because an .ipk is a compressed archive. Download it as above, then:

Install by hand on OpenWrt 25.12 and later

cd /tmp && tar -xzf relayant-agent.ipk && tar -xzf data.tar.gz -C / && tar -xzf control.tar.gz ./postinst
sh ./postinst

To remove it, stop it with /etc/init.d/relayant-agent stop. Then delete /usr/sbin/relayant-agent, /etc/init.d/relayant-agent and /etc/config/relayant, and the relayant zone and relayant_relay rule from /etc/config/firewall.

Update and remove

The package does not update itself. To update, download the new package and install it the same way; the settings are kept. To remove it, opkg remove relayant-agent, which takes its firewall zone away. Then remove it from the site in the portal.

The host's firewall

The relay connects to the agent's forwards on the agent's own interface, relayant0, on TCP ports 41000 to 41999. The agent does not open the host's firewall itself, because the host is not ours. A Linux host that drops incoming traffic on new interfaces needs one rule, added once:

Allow the relay's connections

# ufw
sudo ufw allow in on relayant0 proto tcp to any port 41000:41999
# firewalld
sudo firewall-cmd --permanent --zone=trusted --add-interface=relayant0 && sudo firewall-cmd --reload

On a router the package adds this rule as its own zone, as the table above says.

The agent's tunnel uses addresses in 10.99.0.0/16. If the site's own network uses that range, the host loses its route to those addresses while the agent runs. Use a box there instead, or talk to us. The agent logs a warning at start when it sees the overlap.

What a software agent cannot do

The software agent is one more host on the network, so a few things differ from a box:

Devices that are switched off. A host sees only what is in its own network cache. A device that is off may drop out of the list until it is on again. The router package sees the router's DHCP leases, so it does better.
Other VLANs. Devices on another network appear only if that network is routed to the host.
Wi-Fi. Client isolation on many access points hides other devices. Use a wired host.
Firmware. The agent does not flash the host's firmware. On a router, only installing the next package updates it.
The host's own DHCP and DNS. The agent does not change them.

Everything else is the same as a box: the tunnel, remote access, local relays, discovery and device monitoring.

If it does not work

The agent does not come online. Check the host has outbound internet. The tunnel needs outbound UDP, which some private mobile APNs and business firewalls block. Read the log: journalctl -u relayant-agent -f, or logread -e relayant-agent on a router. A wrong or already-used setup code is named there by its last four characters. A used code needs Re-pair on the Boxes page.

Online, but it finds nothing. The host is on Wi-Fi, or on a different network from the devices. Move it to a cable on the same network, then choose Resync devices.

Devices are found, but connecting to one fails. The host's firewall is dropping the relay's connections. Add the rule above.

Still stuck? Email [email protected] with the site name, which form you installed, and the last 50 lines of the log.

Something in this guide is wrong or missing? Tell us: [email protected].