Isolated browser support¶
Browser support exposes one operator-started, dedicated RF Sentry Chrome profile to diagnostic tools on the appliance. It is not an appliance service, a second acquisition path or permission to attach to your everyday browser. For normal installation see workstation client.
DevTools controls the attached profile
CDP access is effectively full browser control. Never use this profile for email, passwords, administration or unrelated sites. Bind both ends to loopback, keep normal Chrome storage separate, and end the SSH tunnel when support finishes. Do not publish DevTools through a gateway route, firewall opening or persistent daemon.
Choose the session type¶
| Entry point | Browser storage | Background flags | Typical use |
|---|---|---|---|
Unified client debug launch |
Separate reusable debug profile by default | Workstation anti-throttling flags | Repeatable support with retained local data |
Unified client debug launch --fresh |
New disposable OS-temporary profile | Same Workstation flags | Deliberate cold-start investigation |
| Linux/Windows source script | New disposable profile by default | No Workstation anti-throttling flags | Transparent checkout-based fallback |
Fresh/source sessions do not contain your normal or reusable profile's archive.
An empty history there does not show that reception failed. Source scripts can
explicitly retain a disposable profile for an investigation; see their
tools/browser-debug/README.md commands and cleanup notes. There is no macOS
source launcher; use the packaged macOS debug executable.
Configure and launch the packaged helper¶
Use the unified executable for your OS/architecture from
published binaries. Choose optional
Browser support in normal graphical setup or run rfsentry-client debug
gui to open its loopback-only setup surface. It can choose Chrome, the URL and
reusable data directory, launch reusable/fresh sessions, display/copy the tunnel
command and install a separate rfSentry Debug shortcut.
The shortcut uses a managed per-user helper copy, so moving the downloaded
executable does not break it. It does not alter the normal shortcut/profile.
For example, replacing the reserved hostname and sample account with your own:
rfsentry-client debug install \
--url https://radio.example:8443/ \
--ssh-target operator@radio.example \
--desktop
rfsentry-client debug launch
Windows uses .exe and Windows paths. Installation also accepts --chrome,
--data-dir, --debug-port, --pi-port and --dry-run. Launch accepts those
connection/profile overrides plus --fresh; launch overrides are per-session,
whereas GUI saving / install persists settings. print-tunnel-command accepts
the launch options and prints the command without starting Chrome or SSH.
The saved debug configuration wins. On first setup a saved normal-client HTTPS
URL and Chrome path seed it; otherwise the
configured bootstrap URL
is used. Any operator-selected HTTPS hostname/IP/port is allowed, not a compiled
host list. Credentials, query strings and fragments are rejected. Choosing it
does not alter certificate names or gateway ALLOWED_ORIGINS.
The SSH target defaults to the URL hostname (or RFSENTRY_SSH_TARGET); an explicit
or saved --ssh-target can select an OpenSSH alias/account. No SSH account is
compiled in. Setup does not establish a tunnel or weaken TLS validation.
Connect both loopback endpoints¶
Chrome listens on workstation 127.0.0.1:9222 by default. The reverse tunnel
listens on appliance 127.0.0.1:9223. These are DevTools ports, not the
UI/API listener (default 8443) or dedicated IQ listener (default 8444).
Keep Chrome and its launcher open. In a second workstation terminal, run the helper's displayed command, for example:
On Windows use ssh.exe; install the OS OpenSSH Client if absent. Both ports
must be free and SSH policy must allow the loopback reverse forward. Bind neither
end to 0.0.0.0. The helper waits for Chrome to exit; keep the process alive for
normal disposable-profile cleanup.
Changing --debug-port changes the tunnel's destination; changing --pi-port
changes its appliance listener. For a different appliance-side port, give the
CDP helper the matching --endpoint=http://127.0.0.1:PORT. The packaged launcher
also reads RFSENTRY_CHROME_DEBUG_PORT for its launch-port default.
Select the application, then inspect¶
Run the source helper on the appliance with the repository's pinned Node:
cd ~/rfsentry
./scripts/node-toolchain.sh run node tools/browser-debug/rfsentry-cdp.mjs list
./scripts/node-toolchain.sh run node tools/browser-debug/rfsentry-cdp.mjs inspect
The helper reads central /etc/rfsentry/appliance.conf; an explicit
RFSENTRY_APPLIANCE_CONFIG selects another public file. If the central file is
absent on an older install, it can use CANONICAL_ORIGIN / ALLOWED_ORIGINS in
/etc/rfsentry/api.conf. RFSENTRY_API_CONFIG explicitly selects that path.
Malformed/unavailable configuration fails closed rather than guessing a host.
To narrow the session to one origin, use RFSENTRY_URL or an explicit option:
./scripts/node-toolchain.sh run node tools/browser-debug/rfsentry-cdp.mjs list \
--appliance-url=https://radio.example:8443/
That selection replaces, not expands, fallback origins. The helper accepts only a loopback HTTP DevTools endpoint, excludes unrelated origins, refuses to choose between multiple primary RF Sentry pages and verifies the selected pop-out's exact main-application opener origin. Keep one primary app page open. This is origin authorization, not a replacement for Chrome's certificate checks or proof that every page at that selected origin is trustworthy. There is no arbitrary JavaScript/SQL command in this helper.
Start with small, bounded checks¶
| Command | Evidence / important limit |
|---|---|
list |
Authorized primary target descriptions; no frame decoding or playback |
inspect |
Secret-free lane/DSP/job/decoder-start snapshot; not tokens, cookies or archive contents |
graphics |
Display backend/fallback, canvas geometry, isolation and GPU capability limits; not total VRAM or rendering throughput |
cadence --seconds=15 |
Bounded animation/overlay intervals and long-task timing; not a GPU-completion measurement or zero-overhead probe |
console --seconds=60 |
Bounded console/exception/log collection; review output for application content before sharing |
enrichment |
Fixed capability/HEAD/first-64-KiB FCC relay check plus storage capability; not corpus hydration |
Detailed callsign/Heard Stations queries, fixed UI actions and subsystem helpers
remain documented in tools/browser-debug/README.md and the helper's usage.
Some commands change state: for example station-open, set-spectrum,
set-enrichment-policy, receiver start/stop, reload and decoder preparation.
Use only the action approved for the investigation, not a long command list
as a diagnostic checklist. Policy changes can trigger large workload transitions;
see FCC modes. A reload interrupts the browser-owned
IQ/DSP/decoder session even if the appliance service was not restarted.
For decoder-start faults, start the chosen lane only when authorized, wait for DSP ready, then inspect Decoder workspace's input target and stated block reason. The IQ substrate monitor is a useful input/ABI/continuity control, not protocol validation. Protocol decoders already exist; consult the shipped catalog for actual requirements, rather than the old Phase 6B.1A-era support note.
Interpretation and privacy¶
Cadence temporarily instruments animation/overlay timing and restores its hooks after the requested interval. Avoid overlapping heavy profiling or corpus work with it. Browser heap, configured cache capacity and GPU limits are not total resident memory; distinguish observed counters, estimates and resource domains.
Sanitized snapshots have deliberately restricted fields. Console output, screenshots and received messages still need review before sharing. Keep captures, raw data and client profiles out of Git. A successful diagnostic does not complete or alter the acceptance ledger.
Profile lifetime and cleanup¶
Reusable storage defaults beside the normal profile at rfsentry/debug-profile
under the OS user-data directory. Settings are separate debug-client.json
under the user-config rfsentry-client directory. A selected reusable directory
must be empty or carry .rfsentry-debug-profile.json; it cannot be the normal
client profile. Use fast local storage for large archives. Changing directories
does not migrate or delete the previous profile. Fresh sessions always use OS
temporary storage, regardless of that reusable setting.
- Stop the SSH tunnel with
Ctrl+C. - Close the isolated Chrome windows; allow the launcher to finish.
- If needed, confirm the appliance tunnel listener has gone:
Reusable data remains for next time. launch --fresh creates a separate temporary
profile and removes it after Chrome exits; it does not clear reusable data.
rfsentry-client debug uninstall removes the platform shortcuts/app wrappers
(and launcher icons where applicable), not the shared managed helper copy,
saved debug settings or reusable browser data.
Clear-cache removes the entire debug profile
After closing that profile's Chrome processes, rfsentry-client debug
clear-cache deletes the configured reusable profile with its ownership
check. This includes FCC, OPFS, IndexedDB, DVR and learned history, not just
downloaded cache files. Export/back up required evidence first. Debug
settings survive. Use --fresh when a cold test should leave retained data
intact; do not mark an unrelated profile as owned to bypass cleanup checks.
Connection troubleshooting¶
- Refused on 9223: check the SSH tunnel is still running and points to the launched workstation profile/port. An open Chrome window alone does not prove the tunnel exists. Inspect the port listener; do not infer a sandbox restriction from a connection error or start another browser without the operator.
- Remote forward failed: another session may own the appliance port or SSH policy may forbid forwarding. Check ownership before changing policy; never solve it by exposing DevTools publicly.
- No matching page / multiple pages: compare the configured URL and helper's authorized origins, then close stale primary app windows. A portal is not a second receiver owner; see interface ownership.
- Certificate warning: install/verify the appliance public root from its
/trust/page, then use the trusted canonical URL and correct certificate names/trust. Do not disable Chrome TLS or web-security checks. - Capabilities or IQ unavailable: consult connection troubleshooting. Debug access proves neither streaming readiness nor decoder validation.
The Linux Mint and Windows source commands remain in tools/browser-debug/README.md
for checkout-based support. This chapter reconciles their ownership/security
boundaries with the packaged launcher; it is not new live qualification.