Workstation client and browser profiles¶
The optional rfsentry-client utility installs a branded Chrome application
on the analysis workstation, not the Raspberry Pi appliance. It creates
launchers and a dedicated browser profile; it does not own receivers, change
gateway settings, or install DSP outside the browser.
RF Sentry also works in an ordinary browser tab. Its shipped web manifest supports Chrome's application-install flow. Neither option requires the client utility, but neither guarantees a custom profile directory or Workstation flags. Chrome is the reference browser; an installed shortcut is not evidence that OPFS, SharedArrayBuffer, WebGPU or a decoder's acceptance checks have passed.
Get and install the client¶
Choose the rfsentry-client-<os>-<arch> asset for the workstation from
a published release.
If a release is unavailable, build the client from source.
The same executable provides optional
operator-started browser support through graphical setup
or its debug command namespace; normal reception never receives debug flags.
On Debian, Ubuntu, Linux Mint or Raspberry Pi OS desktop workstations, prefer
the .deb matching amd64 or arm64. It installs the executable, icon and
rfSentry Client Setup application-menu entry. Setup can optionally create a
separate rfSentry Debug per-user shortcut. Installing a package does not
configure the Pi or select the workstation's appliance URL for you.
Windows and macOS use the portable binary matching their OS/architecture.
Windows binaries end in .exe. A downloaded Linux/macOS executable may need
its execute permission restored, for example:
That filename is an AMD64 Linux example, not the correct choice for every workstation. See published binaries for all targets.
Graphical setup¶
Run the executable without arguments, or run rfsentry-client gui. Setup opens
a local Chrome app window backed by a random-port 127.0.0.1 HTTP server.
Its embedded assets, restrictive CSP and per-session request token keep this
setup surface local; it does not receive appliance authentication credentials.
Choose the appliance URL, Chrome executable, launch mode, browser-data directory,
desktop shortcut and optional start-at-login setting. Setup shows the exact
Chrome launch command. Native directory selection uses Windows Forms on Windows,
osascript on macOS, or zenity/kdialog on Linux; manual path entry is always
available. Use Close setup or terminal Ctrl+C to end setup. The current
server also has a fixed 45-minute lifetime, not an activity-reset idle timer.
The optional Browser support panel opens isolated support setup within that same loopback server. Enabling it creates separate debug settings, profile and shortcuts and never alters the everyday client profile.
Appliance URL and certificate trust¶
There is no built-in appliance hostname or IP address. Use the canonical UI/API URL from appliance identity, not the dedicated IQ streaming URL. The browser discovers that separate endpoint from the gateway. Use one canonical origin consistently: changing hostname, scheme or API port creates a different OPFS/IndexedDB storage home, even on the same appliance.
For a new setup, enter the URL or set RFSENTRY_URL. To supply the initial
URL from a file, point RFSENTRY_APPLIANCE_CONFIG at a file on the
workstation. Both standard and debug setup accept a full appliance.conf
or a minimal file like this one.
Use your own hostname. The launcher reads PUBLIC_HOST and API_PORT
(default 8443 when omitted). The Pi manages the other settings, including
certificates, discovery and archives. Without an explicit file path, the
launcher checks the workstation's /etc/rfsentry/appliance.conf.
RFSENTRY_URL takes precedence when choosing initial defaults. Later launches
use saved settings. Explicit install options override saved settings or a
supplied JSON configuration.
Normal setup requires HTTPS, except for HTTP on loopback during local development. Debug setup requires HTTPS. Neither bypasses certificate validation or authorizes a new gateway origin. Trust the appliance certificate and configure its SANs/ allowed origins correctly rather than adding insecure Chrome flags.
For an appliance using the preferred private-CA mode, visit its /trust/ page
first. Install the one public appliance root using the tailored mobile/desktop
instructions and verify its fingerprint with sudo rfsentry-config trust on the
appliance. That same root validates appliance-authorized rfSentry Servers; leaf
renewal does not require another client import.
macOS application identity¶
The optional macOS object in client.json configures bundleId and
launchAgentId. The separate debug-client.json accepts macOS.bundleId;
browser support never installs a login agent. These local OS identifiers are
not appliance URLs, DNS names to resolve, or certificate-issuance policy.
Fresh installations use the project namespace in the packaged
identity-defaults.json: org.rfsentry.client for the normal bundle and login
agent, and org.rfsentry.client.debug for the debug bundle. To customize before
installation, pass --bundle-id net.example.radio-client and
--launch-agent-id net.example.radio-login to install. The debug installer
accepts its own --bundle-id net.example.radio-debug. Use identifiers appropriate
to your organization; letters, digits, hyphens and dotted components are allowed.
An external normal-client configuration can be passed with install --config
/path/to/client.json, for example (customize the appliance URL):
{
"schemaVersion": 1,
"url": "https://radio.example:8443/",
"mode": "workstation",
"macOS": {
"bundleId": "net.example.radio-client",
"launchAgentId": "net.example.radio-login"
}
}
On macOS, omitted identifiers are recovered from installed rfSentry bundle and login-agent plists before defaults are considered. Successful installation saves them in the client configuration; GUI updates preserve them too. Discovery uses the application path and metadata, with no compiled legacy namespace. A conflict, ambiguous login agent, or unreadable bundle stops installation before writes. Existing browser URL, profile, and autostart preferences are preserved.
To deliberately change an installed identifier, first remove its launcher using the client, sign out and back in to retire any loaded login agent, then install with the new configuration. Normal uninstall preserves browser data. Debug shortcut removal also preserves debug settings; supply the new debug identifier explicitly when reinstalling. No automatic identity rename occurs during upgrades.
Linux and Windows use stable project-named shortcuts and have no reverse-DNS bundle/login-agent identity. Their appliance URLs and operator settings remain configurable; the macOS fields do not rename their shortcuts or packages.
CLI installation and maintenance¶
The GUI and CLI use the same installation engine. This example uses a reserved hostname and illustrative local storage path; replace both with your own values:
rfsentry-client install \
--url https://radio.example:8443/ \
--mode workstation \
--data-dir /fast/local/disk/rfsentry/chrome-profile
rfsentry-client doctor
rfsentry-client print-launch-command
rfsentry-client launch
On Windows use rfsentry-client.exe and Windows path syntax. install also
accepts --chrome, --desktop, --autostart, --config PATH,
--non-interactive and --dry-run. JSON configuration is versioned and rejects
unknown fields. Dry-run resolves settings/Chrome and prints the plan without
installing files; it does not prove the selected profile can be claimed.
update rebuilds launchers from saved settings. It does not download a new
client binary, update the appliance, or reload an already running application.
doctor (optionally --json) checks the executable/profile/launcher, HTTPS
health and appliance-reported canonical origin. Missing canonical metadata is
unverified, not a guessed host. Browser capabilities are checked after launch,
not established by doctor.
Standard and Workstation modes¶
Workstation is the initial mode; saved choices are preserved. Standard uses:
Workstation additionally uses:
--disable-background-timer-throttling
--disable-renderer-backgrounding
--disable-backgrounding-occluded-windows
These relax Chrome's background policies for an RF workstation and may increase CPU/power use. They do not disable application-owned hidden-view suspension, guarantee uninterrupted scheduling, or increase V8's heap limit. Neither mode disables sandboxing, TLS validation, web security, site isolation or GPU safety; neither forces Vulkan, WebGPU, ANGLE or software rendering. There is no supported arbitrary-flag field or V8 heap override.
Close all windows/processes using the managed profile before changing mode, Chrome path or profile directory and relaunching. Chrome's first process for that profile owns its flags; another window does not reliably change them.
Storage, profile changes and uninstall¶
Use fast local storage with space for FCC data, received products and DVR.
The normal profile defaults under the user's OS data directory:
%LOCALAPPDATA% on Windows, ~/Library/Application Support on macOS, or
$XDG_DATA_HOME / ~/.local/share on Linux, then rfsentry/chrome-profile.
Settings live in rfsentry-client/client.json under the OS user-config directory.
Installation claims only an empty directory or one with its
.rfsentry-client-profile.json ownership marker. Never point it at an ordinary
Chrome profile. A directory change selects different storage; the utility does
not migrate or delete the old profile. Record the old path before changing it
or uninstalling if you need its retained evidence later.
Normal uninstall removes launchers, installed icons and client settings but preserves browser data. The GUI uses this non-destructive behavior. Removing an OS package and removing the per-user launcher/profile are separate operations.
Profile deletion includes retained evidence
rfsentry-client uninstall --purge-data --yes explicitly deletes the
managed profile, including its OPFS, IndexedDB, DVR, corpus and learned-state
data—not merely HTTP cache. It requires the ownership marker and refuses
home, config and root paths. Close that profile's Chrome processes first.
Back up/export wanted evidence before requesting deletion; never add an
ownership marker to make an unrelated directory eligible for removal.
Use storage controls for bounded DVR retention and OPFS management. Chrome flags are not a substitute for application resource budgets. The separate debug profile's lifetime/cleanup is explained in browser support.
Chrome application install and icons¶
The web manifest provides standalone display metadata, PNG/touch icons and maskable variants. Chrome's install affordance is optional; no service worker was introduced solely to make installation possible. Loading the application still needs the appliance; a shortcut is not an offline mirror of the server.
Chrome can retain installed application icons after ordinary refresh. Icon URL versions change with regenerated assets, but removing/reinstalling an old Chrome-installed app may be necessary to update its shell icon. Do not clear all origin data merely to repair an icon.
Published binaries¶
tools/rfsentry-client/build-release.sh produces six executables, two
Debian packages and SHA256SUMS in ignored tools/rfsentry-client/dist/:
| OS target | Architectures | Unified artifact |
|---|---|---|
linux |
amd64, arm64 |
rfsentry-client-linux-<arch> plus matching .deb |
windows |
amd64, arm64 |
rfsentry-client-windows-<arch>.exe |
darwin (macOS) |
amd64, arm64 |
rfsentry-client-darwin-<arch> |
Debian names are rfsentry-client_<arch>.deb. The client retains its version
inside the package and executable; rfsentry-client --version and
rfsentry-client debug version work without loading appliance configuration.
Use dpkg-deb --field <download>.deb Version to inspect an uninstalled package.
The release tag and checksum identify the particular download. Keep downloads
from different releases in separate directories. Portable Linux ELF downloads do
not themselves supply an application-menu icon; the package/installed launcher
provides that integration. Executables embed their PNG/ICO/ICNS assets.
Release assets can be downloaded individually. Verify them against the
release's SHA256SUMS with sha256sum, shasum -a 256 on macOS, or
Get-FileHash -Algorithm SHA256 in PowerShell.
For development builds, the qualification workflow calls Packages / Client
for the selected source and retains the verified client bundle for 30 days.
Extract the Actions artifact before using the files. Release / Project
handles publication for v* and client-v* tags after the applicable gates.
See the qualification and promotion guide.
Source build and ownership¶
Go 1.24+ is a build dependency. The release script runs Go tests and the
configured-origin tests using the repository's pinned Node toolchain, and needs
dpkg-deb for Linux packaging. The binaries need Chrome/Chromium at runtime,
not Go, Node, Python, Electron or a GUI toolkit runtime. Optional native directory
pickers and SSH for support have their separate OS requirements.
./tools/rfsentry-client/build-release.sh
./scripts/node-toolchain.sh run node tools/generate-client-icons.mjs
The second command deterministically regenerates embedded/client/browser icons;
it is not part of ordinary client installation. The source README and
model.go, appliance.go, chrome.go, engine.go, gui.go,
debug_config.go, debug_session.go, packaging script and
.github/workflows/client-release.yml define this behavior. These source-backed
instructions do not replace live/browser acceptance.