Installing GopherTrunk on Windows 11

This is the path the prebuilt installer lays down for you. Five minutes from a fresh download to a working gophertrunk sdr list.

1. Download the installer

Go to the GopherTrunk releases page and download the asset named:

gophertrunk-<version>-windows-amd64-setup.exe

If you’d rather skip the installer and run from a folder, grab the matching gophertrunk-<version>-windows-amd64.zip and extract it anywhere — the contents are the same.

Why is the download blocked? Windows SmartScreen sometimes warns on installers it hasn’t seen before. Click More info → Run anyway, or right-click the file → Properties → check Unblock. The installer is unsigned today; signing is on the roadmap.

2. Run the installer

Double-click setup.exe and accept the defaults. The installer:

  • Copies gophertrunk.exe to C:\Program Files\GopherTrunk\ — a single static binary, no DLLs to ship. This is the only thing that goes in Program Files.

  • Asks you for one data folder (the “Select your GopherTrunk data folder” page after the Tasks step, defaulting to %USERPROFILE%\Documents\GopherTrunk). Everything that isn’t the program lives here, in a tidy subfolder tree Setup creates:

    Documents\GopherTrunk\
  config\       config.yaml + your talkgroup / RID CSVs
  recordings\   voice-call recordings (.wav / .raw)
  iq\           raw IQ baseband captures
  exports\      CSV / PDF exports
  data\         calls.db + caches
  logs\         decoded-message logs
  web\          the browser consoles (standard + Signal Lab + Config Builder)

    You can point this anywhere you can write to — a USB stick, a network drive, your desktop. Setup seeds a starter config.yaml into config\ (an existing one is never overwritten).

  • Bundles Zadig (the WinUSB driver-binding tool) next to the daemon and adds a Start Menu shortcut “Install RTL-SDR driver (Zadig)” so you don’t have to chase a separate download.
  • Adds Start Menu entries for the daemon, the config template, the three browser-based web consoles (open them straight from web\ — setup + quick-start guide: Web console), and these instructions.
  • Optionally adds C:\Program Files\GopherTrunk to your system PATH so you can run gophertrunk from any PowerShell window (off by default — tick the “Add GopherTrunk to my PATH” checkbox during install if you want it).

When the wizard finishes, it’ll offer to open this document, a console window, Zadig (to bind the WinUSB driver — see §3), and the web console in your default browser. All are harmless to skip; the Zadig one defaults off.

3. Install the WinUSB driver via Zadig (one-time, for each dongle)

Windows ships an RTL-SDR DVB-T receiver driver by default — that driver is what you’d use to watch broadcast TV, and it’s the wrong driver for SDR work. We need to swap it for WinUSB on a per-device basis. The installer bundles Zadig (GPL-3.0, from https://zadig.akeo.ie) so you don’t have to chase a download.

  1. Plug in the RTL-SDR dongle. The same flow works for any 0bda:2838 device — generic RTL-SDR Blog units, the NooElec NESDR Smart v5, and equivalent clones.
  2. Launch Zadig via Start Menu → GopherTrunk → “Install RTL-SDR driver (Zadig)”. Approve the UAC prompt. (Alternatively, on the last page of the installer there’s an unchecked “Run Zadig now to bind the WinUSB driver” option — tick it before clicking Finish.)
  3. Options → List All Devices so the RTL-SDR shows up.
  4. From the dropdown, pick the dongle. It’ll typically appear as Bulk-In, Interface (Interface 0) or RTL2832U (the NESDR Smart v5 reports as RTL2838UHIDIR).
  5. With WinUSB selected as the target driver, click Replace Driver (or Install Driver, first time).
  6. Wait ~10 seconds for the success dialog.

You only do this once per dongle. If you ever want the dongle to work as a TV tuner again, run Zadig in reverse and pick the manufacturer driver.

4. Verify everything works

Open Windows Terminal (or PowerShell) and run:

gophertrunk version
gophertrunk sdr list

sdr list should print one line per attached dongle with its driver, index, serial, and product string. The TUNER and gains columns are blank by design — they need the device to be opened (USB claim + RTL2832U baseband init + I2C tuner probe), which sdr list skips so the command is fast and never collides with a running daemon. Pass --probe when you want those columns filled:

gophertrunk sdr list --probe

If you see no SDR devices found and you’re sure the dongle is plugged in, the WinUSB driver swap probably didn’t take — re-run Zadig with Options → List All Devices checked and verify the “Driver” column shows WinUSB for your dongle.

If you didn’t tick the PATH option during install, run from the install folder instead:

cd "C:\Program Files\GopherTrunk"
.\gophertrunk.exe sdr list

5. Configure and start the daemon

The installer asked you for a data folder (default Documents\GopherTrunk) and seeded a config.yaml in its config\ subfolder. It also set the GOPHERTRUNK_CONFIG user environment variable to point at that file, so the daemon discovers it automatically — no -config flag needed. (A second variable, GOPHERTRUNK_HOME, points at the data folder itself.) Use the Start Menu shortcut “Edit my config.yaml (Notepad)” to open it, set your device serial + control-channel frequencies, and save.

The seeded config.yaml uses config-relative paths (../recordings, ../data/calls.db, ../iq, ../logs), so the daemon writes recordings, the database, IQ captures, and logs into the sibling folders under your data root automatically — no absolute paths to edit. You can still hard-code an absolute path (or use %GOPHERTRUNK_HOME%\...) if you want files somewhere else.

Then start the daemon:

gophertrunk run

The daemon prints config: loaded <path> on startup so you can confirm it picked up the right file. To override (e.g. running against a second config for testing), use -config:

gophertrunk run -config "C:\path\to\other.yaml"

If you drop multiple *.yaml files into the config\ folder (e.g. config.yaml + prod.yaml + test.yaml), the daemon prints a numbered menu on startup and asks which one to load. Pick the number, press Enter, and that file is used. Set -config or GOPHERTRUNK_CONFIG to skip the prompt for unattended runs (a non-interactive launch — Windows service, scheduled task — auto-selects the first file and logs the choice).

A read-only reference copy of the full annotated template lives at C:\Program Files\GopherTrunk\config.example.yaml (Start Menu → “Configuration template”).

Logs stream to the terminal. Press Ctrl+C to stop cleanly.

For a long-running setup, register GopherTrunk as a Windows service with NSSM — that’s the simplest path until a native service manifest ships:

nssm install GopherTrunk "C:\Program Files\GopherTrunk\gophertrunk.exe" `
  run -config "%USERPROFILE%\Documents\GopherTrunk\config\config.yaml"
nssm set GopherTrunk AppDirectory "C:\Program Files\GopherTrunk"
nssm start GopherTrunk

Point -config at the config.yaml inside your data folder’s config\ subfolder. A service runs as a different account, so use the absolute path here rather than relying on the per-user GOPHERTRUNK_CONFIG variable.

Uninstall

Settings → Apps → Installed apps → GopherTrunk → Uninstall. The uninstaller removes the install folder and every Start Menu entry, strips GopherTrunk from your PATH (if you opted in), and clears the GOPHERTRUNK_CONFIG / GOPHERTRUNK_HOME env vars. It then asks whether to also delete the Setup-managed parts of your data folder — the config, data, logs, and web subfolders. The default is No. Even if you say Yes, your captures (recordings, iq, exports) are always kept so you never lose recordings on an uninstall.

Troubleshooting

Symptom Likely cause
gophertrunk not recognised PATH wasn’t added — open a fresh terminal or run from C:\Program Files\GopherTrunk directly.
sdr list prints nothing Zadig WinUSB swap didn’t take — see step 3.
usb: device disconnected mid-stream The DVB driver re-attached itself — re-run Zadig.
WinUsb_Initialize fails The dongle is bound to the wrong driver — re-run Zadig and pick WinUSB.
ERROR_GEN_FAILURE / device rejected request on sdr list Clone-dongle cold-start quirk — a USB control transfer is NAK’d during bring-up. v0.2.x absorbs this automatically: the sacrificial warmup probe, a control-pipe clear-and-retry, and (for R820T/R828D tuner init on NESDR v5 silicon) a per-chunk retry + chunk-size halving fallback all recover from it. If it still persists, the probe error prints a --- USB diagnostics --- block (bound driver, device/config descriptors, a control-IN read probe) — copy that whole block into a GitHub issue. Meanwhile: try a different USB port (front vs. rear use different host controllers), avoid hubs and extension cables, and confirm gophertrunk sdr doctor shows WinUSB (not libusbK) bound to interface 0.
Smart Screen blocks the installer Right-click → Properties → Unblock, or More info → Run anyway.

For anything else: open an issue at https://github.com/MattCheramie/GopherTrunk/issues with the gophertrunk version output and the first few lines of the daemon log.