Skip to content

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:

ssh -N -o ExitOnForwardFailure=yes \
  -R 127.0.0.1:9223:127.0.0.1:9222 operator@radio.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.

  1. Stop the SSH tunnel with Ctrl+C.
  2. Close the isolated Chrome windows; allow the launcher to finish.
  3. If needed, confirm the appliance tunnel listener has gone:
ss -ltn 'sport = :9223'

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.