How to use qsonaut

Step by step. Each part can be read on its own — pick one from the list on the left.

Installing

Packages are on the download page.

macOS

1. Open the .dmg file and drag qsonaut into Applications.
2. The program has no Apple certificate yet, so the first time open it with a right-click (or Ctrl-click) → Open → Open. After that it starts normally.
3. If macOS says the application is “damaged”, remove the download flag in Terminal: xattr -dr com.apple.quarantine /Applications/qsonaut.app

macOS asks for keychain access — that is where the log's keys are kept. Choose Always Allow. When synchronising it asks about the local network: choose Allow. After an update the questions may come back, because without a certificate the system treats the new version as a new program.

Windows

Run the .exe installer (or the .msi). Windows shows “Windows protected your PC” — choose More info → Run anyway. On the first sync Windows Firewall asks about network access: for the local network, allow it on private networks.

Linux

The AppImage runs without installing: chmod +x qsonaut_*.AppImage and start it. The .deb (Debian, Ubuntu, Mint) and .rpm (Fedora, openSUSE) packages install with your package manager. The program needs WebKitGTK 4.1.

First start

The welcome screen offers three ways in:

• I am starting a log — the first computer with qsonaut. Give the log a name (your callsign, for example) and name this computer. A log with your key is created.
• I am adding this computer — your log is already on another computer. This one gets its own key and the log arrives when you pair them (see Synchronising).
• I am recovering a log — you have a recovery kit and its passphrase.

Already have a log in another program? After creating the log, import it from ADIF (Import).

Station setups (prepared setups)

A setup describes the station as it is right now: callsign, operator, locator, QTH, power, the list of rigs and antennas, your own activation references and a contest. Every contact logged with a setup gets these details copied — changing the setup later never changes QSOs already saved.

Creating and switching

1. On the Operating screen, click + Add in the top right corner.
2. Name it (“Home QRO”, “Riverside park”), pick an icon and fill in the fields. Enter rigs and antennas separated by commas — the first is the default, the rest you pick on the radio bar.
3. Your own references (POTA, WWFF, PGA…) appear once the matching program is turned on.
4. Save. The setup's tile sits at the top of Operating; a click makes it active.

Setups are shared by all your devices — one prepared on the laptop is on the shack computer too. The pencil on a tile edits it, the bin deletes it everywhere (saved contacts stay).

Examples

Logging contacts

The radio bar

Below the setups: band, frequency, mode, power, rig and antenna. Type the frequency and the band follows. What you set here applies to the next contacts.

The entry

1. Type the callsign. The Other station panel shows earlier contacts with it, the bands you already have it on, and details from QRZ/HamQTH.
2. RST reports default by mode (59/599; for FT8 they stay empty, since that report is in dB).
3. Enter the other station's references (park, municipality…) in the program fields. qsonaut says right away whether it is a new reference and which contact with it this is.
4. Enter or Save QSO saves the contact.

More fields reveals country and DXCC entity, CQ and ITU zones, IOTA and propagation (Es, tropo, MS, EME, satellite…). Propagation carries over to the next contacts until you change it. For a contact made a moment ago, click the clock and enter the UTC date and time.

What the screen tells you

• ★ New one — what the contact brings: DXCC, a band or mode for an entity, a locator square, a zone or a program reference. GRID/BAND is a square you already have, but not on this band (6 m and up).
• Distance and bearing — from your locator to the other station's.
• Programs — progress of the turned-on programs; during an activation, the QSO count.
• Bands — how many contacts you have on each band, and today.

The log and the map

The Log tab is the whole log: search by callsign, note and reference, the ★ new one and Unconfirmed filters, sorting by column. The gear icon sets the columns (including km), their order, width and the row density.

• Clicking a contact opens its card: correct it, see its history, move it to the trash.
• Trash and To resolve are under More. A conflict appears when two devices changed the same contact independently — you choose which version to keep.
• Map shows locator squares or stations. The band chips above it filter any combination of bands and show how many contacts each has. Clicking a square lists its stations; clicking a station opens its last contact.

Synchronising devices

Each of your devices holds the whole log and works on its own, offline included. When devices can reach each other, they exchange changes. There is no server holding the log — which is why every device is a backup of the others.

Pairing — once per device

Both computers must be on the same Wi-Fi or wired network.

1. On the computer that has the log: Devices → Show pairing code. The code has 8 digits (there is a QR code too) and is valid for 2 minutes.
2. On the new computer: on the welcome screen choose I am adding this computer → Get ready to pair. Computers on the network are listed — choose the one with the log and enter the code.
3. Back on the first computer, approve with Add this device. The log starts to transfer.

Local network and Internet

The sync status is in the top bar, next to the language button. A click opens a panel: Synchronise now, the state of every device and three switches.

The status in the bar

• All devices up to date — each has all your entries.
• Up to date: 1 of 2 — one device is current, the other is waiting for changes (it may be switched off). It gets them as soon as it is reachable again.
• Sync off — both network switches are off.

Disconnecting a device

A lost laptop is disconnected under Devices → the device's card → Disconnect device. It stops synchronising with the log; coming back takes pairing again with new keys.

Award programs

A program counts your progress towards an award from your log — locally, without sending anything anywhere. Each program is a signed file; the signature guarantees nobody changed its rules.

Ready-made programs

The program texts are in Polish for now; the rules work the same in either language.

Adding a program

1. Programs → + Add → choose the program file → Check program. The preview shows the author, the rules and the result on your log.
2. Add to logbook, then turn the program on with its switch in the list.
3. Load the directory with the directory icon in the top right corner of the program's details. With it you see not only the result but also what is still missing.

A turned-on program with references adds fields to the entry line (e.g. “POTA”) and to the station setups. The result is a local calculation — the official credit always comes from the organiser.

Export packages

More → Export packages prepares ADIF files to a program's rules — e.g. an activation log split by park and day. Before saving it shows what goes into the package and what data is missing.

Your own program templates

A program is written in YAML, in the Hamrule format. An example — a local award for 50 PGA municipalities worked on 80 m in 2026:

format: hamrule/2
id: my.pga.80m.2026
name: PGA · 80 m · 2026
version: 1
role: hunter              # hunter | activator | participant
reference_program: PGA    # reference fields appear in the entry line
presentation:
  icon: map               # map | globe | trophy
  unit: municipalities
  description: PGA municipalities worked on 80 m in 2026.
filter:
  start_utc: '2026-01-01T00:00:00Z'
  end_utc: '2027-01-01T00:00:00Z'
  bands: [80m]
  modes: []               # empty = all
  confirmed_only: false
scoring:
  points: 1
  unique_by: [remote_reference]
  multiplier: null
requirements:
  minimum_score: 50
  required_calls: []

What can be counted (unique_by)

Fields combine: [dxcc, band] counts each entity separately on each band. confirmed_only: true takes only contacts confirmed by card or LoTW. A logging section with a contest_id adds the contest to the station setups.

Signing and adding your own program

1. Save the template as a .yaml file.
2. Programs → + Add → choose the file. qsonaut recognises an unsigned template.
3. Sign with my key and check. On the first signature the computer creates its own author key and keeps it in the system keychain. The preview shows the program's result on your log.
4. Add to logbook. Want to pass the program on? Save signed file… — any qsonaut installs that file.

ADIF import and export

Import

1. Log → the import icon → ADIF log… → choose the file.
2. The preview shows how many contacts are new, how many are already in the log (these are skipped) and what cannot be read. Records without a station callsign can be assigned to the callsign you give.
3. Import. Importing the same file again duplicates nothing.

The file must be UTF-8. Unknown ADIF fields are kept and come back in exports.

Export

The export icon: Whole log, Search results or Selected (select contacts in the table). Files for a particular program come from export packages.

QRZ.com and HamQTH

Callsign lookup

Settings → Callsign lookup: choose a service and sign in. When you type a callsign, qsonaut asks for the name, QTH and locator and fills in only empty fields. Answers are cached. HamQTH is free; QRZ.com without a paid XML subscription returns incomplete data (no locator or zones).

QRZ Logbook confirmations

1. Settings → QRZ.com logbook: the callsign and the Logbook API key from the logbook's settings at logbook.qrz.com (needs an XML subscription or higher). A /P callsign has its own logbook and key.
2. In the Log, select contacts → Confirm selected → QRZ.com → Send selected QSOs to QRZ, and later Check confirmations.

Confirmations by QSL file

Two stations using qsonaut confirm contacts directly, with no service in between:

1. Select contacts with one station → Confirm selected → QSL file → Save QSL file… and send the file to them (e-mail, messenger).
2. They: Log → import → Confirmations from the other station… → load the file, check the sender, accept the confirmations, then save a reply file.
3. You load their reply the same way — matching contacts are confirmed.

The file is signed: the signature protects its content; check the sender through the channel it came by.

WSJT-X, JTDX and MSHV

1. In qsonaut: Settings → WSJT-X · JTDX · MSHV → turn on Receive contacts from WSJT-X.
2. In WSJT-X: Settings → Reporting → UDP Server 127.0.0.1, port 2237. JTDX and MSHV have a similar UDP server setting.
3. Every Log QSO in WSJT-X lands in the log at once, completed with references, equipment and power from the active setup.

Recovery kit

The computer the log was created on holds its master key — the one that adds and disconnects devices. Settings → Log recovery kit saves that key in a passphrase-protected file (at least 12 characters). Keep the file off the computer, separate from the passphrase.

If you lose that computer, choose I am recovering a log on a new one, point to the kit and enter the passphrase. The contacts come from your other devices when they sync (or from an ADIF export) — the kit carries the key, not the log.

Data and privacy

• The log is in a local database on your computer; Settings → Application data shows where. Passwords and API keys are in the system keychain.
• Callsigns go to QRZ.com or HamQTH only once you set up callsign lookup.
• Once a day the program asks api.qsonaut.app whether there is a new version — giving only its version number and system. The counts are kept only as totals by version, system and country (Cloudflare derives the country from the IP address; the address is not stored). Turn it off under Settings → New versions.
• Switch the interface language in the top bar (PL / EN).

Something missing, or working differently from what is written here? Let me know and I will fix it.