Skip to content

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:

chmod +x ./rfsentry-client-linux-amd64
./rfsentry-client-linux-amd64

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.

PUBLIC_HOST=radio.example
API_PORT=8443

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:

--user-data-dir=<managed-profile>
--app=<selected-URL>
--no-first-run
--no-default-browser-check

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.

rfsentry-client uninstall

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.