Host Deployment · RemoteRF

A RemoteRF host is a computer that is deployed alongside one or more SDRs and provides them a connection to the RemoteRF server over Wi-Fi, LAN, or VPN. Hosts allow you to deploy SDRs in a geographically distributed manner, in order to create large-scale testbeds that span rooms, buildings, or even entire campuses. A single RemoteRF deployment can have many hosts, with each host physically connected to one or more SDRs.

Any Linux computer with network access and USB connectivity can act as a RemoteRF host. For most deployments, a lightweight computer—such as a Raspberry Pi—can fill this role.

A simple Raspberry Pi can act as a RemoteRF host.

Prerequisites

Before proceeding, it is assumed that you have already completed the basic Server Deployment process and obtained the following hardware components:

A Linux-based computer, such as a Raspberry Pi or lightweight desktop computer, which will act as the RemoteRF host. We recommend Ubuntu 24.04 LTS, but other distributions should also work, though they have not been extensively tested. We recommend a fresh install.
At least one supported SDR that will be physically connected to the host over USB.

This guide will assume that the Linux host satisfies the following:

It has been installed with Python 3, ideally managed through conda (or Miniconda).
It can reach the main RemoteRF server over LAN, Wi-Fi, or VPN.
It has reliable USB access to the SDRs you plan to connect.

Quick Guide: If you need help installing Linux, installing Python, or confirming that the host can reach the RemoteRF server, please refer to the following guides.

To install Python, open a terminal and execute the following.

sudo apt update
sudo apt install -y python3 python3-pip python3-venv curl bzip2
python3 --version

The overall flow is the same on Intel/AMD and ARM machines. The only part that changes is which Miniconda installer you download.

Then, check which machine architecture your computer is by executing the following in the terminal.

uname -m

x86_64 means your machine is Intel or AMD
aarch64 means your machine is ARM64

If your machine is x86_64, install Miniconda with:

cd /tmp
curl -fsSLO https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p "$HOME/miniconda3"

If your machine is aarch64, then use:

cd /tmp
curl -fsSLO https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh
bash Miniconda3-latest-Linux-aarch64.sh -b -p "$HOME/miniconda3"

Finally, enable conda, accept Conda's terms of service if needed, and create the RemoteRF host environment with the following.

source "$HOME/miniconda3/etc/profile.d/conda.sh"
"$HOME/miniconda3/bin/conda" init bash
source ~/.bashrc
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r
conda create -n remoterf-host -y python pip

Here, remoterf-host is the name of the conda environment. You should enter this environment essentially anytime you open the terminal of the RemoteRF host by running:

conda activate remoterf-host

The RemoteRF host must be able to reach the main RemoteRF server over your deployment network, whether that is LAN, Wi-Fi, VPN, or another routed connection.

Use the static IP address and ports from your earlier server setup to verify that the host can reach the server with:

nc -vz <server_static_ip> <main_port>
nc -vz <server_static_ip> <cert_port>

For example, if your RemoteRF server uses 192.168.1.50 with ports 61005 and 61006, run:

nc -vz 192.168.1.50 61005
nc -vz 192.168.1.50 61006

If both checks succeed, the host has the network reachability it needs to continue. If either check fails, resolve the network, VPN, firewall, or server configuration issue before starting the host process.

Configuration

With an up and running RemoteRF server, you can now configure the host. Make sure the host is powered on and connected to the same network as the server.

To complete host configuration, open a terminal on the host itself. You can do this by connecting a monitor, keyboard, and mouse to the host, or by signing in remotely over SSH if SSH is enabled. The host does not need to be in its final deployment location yet; as long as it can reach the RemoteRF server during setup, you can configure it now and move it later.

Open a terminal and activate the remoterf-host environment via conda activate remoterf-host. The hostrf commands used below will only work from within this environment. Keep this terminal open throughout this configuration.

Step 1

Install and Verify the Host CLI

Install the RemoteRF host package in the active environment, then make sure the hostrf command is available on the host machine before you continue.

On the host, run:

python -m pip install -U pip
python -m pip install remoterf-host
hostrf --help

Expected result: The package install should complete successfully, and hostrf --help should print a detailed list of available commands and options. If the shell says hostrf cannot be found, reactivate the correct environment and confirm that remoterf-host installed successfully.

Step 2

Choose a Host Name and Create a Token

Choose a name that you want to associate with this specific host, then create its token on the RemoteRF server.

Note: The name of the host should be unique and descriptive, so that you can identify that particular host among others that may get deployed.

Example value used here:

Host name: lab-host-0

On the server, run:

serverrf --host --token-create "lab-host-0" --length 8 --force

Expected result: The server should create the token and print the exact hostrf configuration command you should run later on the host machine.

Example server output:

Host token created and stored at ~/.config/remoterf/db/hosts_auth.env
First start the server with 'serverrf -s'.
Then, on the host you want to set up, run the following:
  hostrf --config --host lab-host-0 "Vn7Kx3QpL9s"

Step 3

Start the Server

On the RemoteRF server machine, start the server before proceeding.

On the server, run:

serverrf --serve

Expected result: The RemoteRF server should start successfully and remain running. Keep this active server session open for the remaining steps below.

Step 4

Apply the Returned Host Command on the Host

On the host machine, run the exact hostrf --config --host ... command returned by the token creation step.

On the host, run:

hostrf --config --host lab-host-0 "Vn7Kx3QpL9s"

Expected result: The host should report that the configuration was successful. At that point, this host name and token are associated with that specific host.

Step 5

Point the Host at the Server

Configure the host with the RemoteRF server address before starting the long-running host process. Use the server static IP or DNS name with the main port, not the certificate port.

Example values used here:

Server address: 192.168.1.50

Main port: 61005

On the host, run:

hostrf --config --addr 192.168.1.50:61005
hostrf --config --show

Expected result: The host should report that the network configuration was saved, fetch the server certificate using the adjacent certificate port, and show REMOTERF_ADDR=192.168.1.50:61005.

Step 6

Start the Host

Start the host process so it can connect back to the already running RemoteRF server.

On the host, run:

hostrf --serve

Expected result: hostrf should connect successfully to the RemoteRF server and remain running.

Step 7

Verify the Host from the Server

On the active serverrf CLI session, confirm that the newly configured host machine is visible to the server.

On the server, run:

hosts status

Expected result: You should see your newly configured host machine listed in the output.

After all of these steps are completed successfully, the host is now fully functional and reachable from the RemoteRF server, as long as it remains on the same network.

Next Steps

Recommended

Next Step

Device Setup

Use this next to attach SDRs to the newly configured host, name them, and confirm they appear correctly inside RemoteRF.