Advanced Configuration

Now that the basic server framework is up, this page serves as a deeper reference for the full ~/.config/remoterf/ file tree, including the optional GitHub Gist status publisher. You may skip this page if you want, since nothing below is critical for a first successful bring-up.

Use this as a reference, not a checklist. Most deployments only need the basic steps above. The files below matter when you want to inspect what the CLI generated, understand what the runtime persists, or make deliberate manual changes.

Reference Layout

Sample `~/.config/remoterf/` tree

Compact reference view of the main server config files. Hover or focus any entry for a brief explanation.

edit by hand CLI preferred DO NOT TOUCH

Hover or focus a file or folder name to see what it does.

~/.config/remoterf/ directory
- server.env CLI preferred
- gist.env CLI preferred
- super_token.txt edit by hand
- devices.yml edit by hand
- certs/ DO NOT TOUCH
- db/ DO NOT TOUCH
- drivers/ directory
  - <device>_schema.py edit by hand

Manual backups: If you want your own backup copy, you can duplicate ~/.config/remoterf/ somewhere else as a manual snapshot. It is best to do this while the server is stopped so the copied state is consistent.

GitHub Gist Status Publishing

RemoteRF can publish lightweight deployment status to a GitHub Gist. This is useful when you want a static web dashboard to show reservation activity, account totals, reserved hours, or other server-side summary data without exposing the RemoteRF server itself to the public internet.

usage statistics

Push status JSON to a public Gist

The server runtime writes the status payload. The website or dashboard reads the raw Gist URL and renders it as a normal JSON data source.

1 Server Runtime

serverrf --serve gathers live usage and reservation summaries.

2 Local Config

gist.env stores the target Gist metadata and publishing credential.

3 GitHub Gist

The configured JSON file is updated on the publishing interval.

4 Static Dashboard

A page fetches the raw URL and renders the latest status snapshot.

What You Need

ID Public Gist ID

Create a public GitHub Gist and copy the long ID at the end of its URL.

https://gist.github.com/user/<gist_id>

JS JSON Filename

Use a stable file name ending in .json. The dashboard raw URL should point at this same file.

PAT Gist Write Token

Create a GitHub personal access token with Gists read/write permission, then keep it only on the server.

gist.env

Configure the Publisher

Run these commands from the same Python environment where remoterf-server is installed:

Step 1

Create the Gist Assets

Create a public Gist, add an empty JSON file, and save both the Gist ID and filename for the CLI step.

Example: See this RemoteRF status Gist. For that URL, the Gist ID is 35d21013e98817dd7fe745a6c8819bfe.

Step 2

Create the GitHub Token

Generate a GitHub personal access token for the server process. The token only needs Gists read/write permission for this feature.

Keep it private: The token belongs in local server config only. Do not paste it into a public Gist, a dashboard page, or this website repository.

Step 3

Store the Target Gist

Use the built-in CLI so RemoteRF writes the expected gist.env values.

on the server, Run:

serverrf --gist --set --id <gist_id> --file <filename>
serverrf --gist --show

Expected result: Running serverrf --gist --show should print the configured Gist ID and JSON filename. If your installed version prompts for the GitHub token, paste the token from Step 2 into that prompt.

Step 4

Restart the Server

Start the server after the Gist config is in place. The status JSON should update automatically while the server is running.

On the server, Run:

serverrf --serve

Check right away: Open the Gist in GitHub and confirm the JSON file changes after the first publishing interval.

Dashboard Hook

The static dashboard side should read the raw Gist file, not the editable Gist page:

dashboard gist source

url

https://gist.githubusercontent.com/<github_user>/<gist_id>/raw/<filename>

The current RemoteRF dashboard renderer expects a JSON object with usage totals and per-device reservation counts:

gist payload shape

json

{
  "usage": {
    "account_count": 60,
    "total_reservations": 214,
    "total_reserved_hours": 417
  },
  "reservation_history_days": 27,
  "reservations": {
    "0": {
      "2026-04-24": 12
    },
    "1": {
      "2026-04-24": 4
    }
  }
}

Restart after changes: If you change the Gist ID, filename, token, or any other Gist setting, stop the active serverrf --serve process and start it again so it reloads gist.env.

Super Token

The super token is an administrator-only master override for direct device access. Normal users should use the reservation API tokens issued by RemoteRF after they reserve a device. The super token exists for administrator testing and urgent debugging when needing to access a device without going through the normal reservation process.

Keep this separate from user onboarding: Do not give the super token to students, lab users, dashboards, public Gists, or client setup guides. Anyone with the value can bypass the normal reservation-token path.

Store the Token Locally

Choose a private admin-only value and store it only on the RemoteRF server. This does not need to be generated by RemoteRF; a human-written value is fine as long as it avoids spaces, is reasonably long, and is not reused from a normal account password.

~/.config/remoterf/super_token.txt

text

mkdir -p ~/.config/remoterf
nano ~/.config/remoterf/super_token.txt

The nano command only opens the file. Type one private token value on the first line, such as my-private-super-token, then save and exit. Leaving this file empty disables the super-token override.

chmod 600 ~/.config/remoterf/super_token.txt

The server reads the super token from ~/.config/remoterf/super_token.txt. After the file is in place, start the server normally:

serverrf --serve

If you change the value while the server is already running, restart serverrf --serve before relying on the new token.

Token Forms

The super token can be passed into the same Python token= argument used by normal reservation tokens:

admin-only token forms

python

from remoteRF.drivers.adalm_pluto import *

# First available unreserved device, local devices first.
sdr = adi.Pluto(token="my-private-super-token")

# Specific device, only if that device is online and unreserved.
sdr = adi.Pluto(token="my-private-super-token_0")

# Specific device even if it is currently reserved.
sdr = adi.Pluto(token="my-private-remoterf-admin-token_0_force")

Use the _force form sparingly, as it can access a device that is already reserved and currently in use, potentially disrupting existing experimentation.

Rotation Checklist

If the super token is exposed to someone who should not have access to it, it should be changed immediately to prevent them from having unfettered access to the server’s devices:

Stop the running serverrf --serve process.
Replace ~/.config/remoterf/super_token.txt with a new private value.
Start serverrf --serve again.