ZeroTrace Companion
First Launch
What to expect the first time you open Companion — permissions, optional driver checks, and the device picker.
The first time you launch Companion, three things happen in sequence: permission grants, optional driver checks, and the device picker. This page walks through each.
Step 1 — Operating-system permission grants
Companion needs permission to read from USB serial ports. The exact grant flow depends on your platform.
| Platform | What you'll see | What to grant |
|---|---|---|
| Windows | First-time Defender / SmartScreen prompt | Allow the binary; Companion does not auto-update silently |
| macOS | "App from unidentified developer" dialog if not yet notarized | Right-click → Open → Open. Subsequent launches open normally. |
| Linux | A udev permission prompt the first time you connect a serial device | Add your user to the dialout group: sudo usermod -aG dialout $USER then log out and back in |
If permission is denied, Companion still launches — but the device picker shows zero ports and you cannot connect.
Step 2 — Device-driver check
Some operating systems and some USB-serial chipsets need a driver before the device appears as a COM port:
- Windows — most modern ZeroTrace devices use a CDC-class chipset that Windows recognises out of the box. For older or third-party-firmware devices, you may need a CP210x or CH340 driver from the chipset vendor.
- macOS — Apple Silicon and recent Intel macOS ship with native CDC support. For legacy macOS, install the chipset's macOS driver.
- Linux — kernel CDC ACM support is built in. No driver install required.
If your device does not appear in the picker after plugging in, check the platform-specific driver guidance in troubleshooting.
Step 3 — The device picker
Companion's main window opens with the device picker as a coverflow of supported ZeroTrace products. Below it, a port panel lists what was found on each USB serial port for the device card you currently have selected.
- Coverflow — flip through the supported devices: ZeroTrace AirLeak, Kit, BLE Logger, HID Firmware, AirLeak Firmware, plus a Custom slot. The card you flip to becomes the active card.
- Per-port identification — Companion probes each port to figure out what is on the other side. The probe runs only against the family of your active card (115,200 baud for HID-class, 921,600 baud for AirLeak), so an AirLeak probe never garbles a HID device sitting on the next port. You'll see one of:
- Match — the port responded and the device matches the active card.
- Mismatch — the port responded but the device is a different family (you can switch cards to it).
- Busy — another application has the port open.
- No response — port exists but did not reply.
- Connect button activates once the matching port is selected.
The picker auto-rescans every 2 seconds, and once a port has been classified its label is sticky — a momentary scan miss won't drop the device from the list.
The picker remembers what you were on
The card you last had selected is saved immediately, even if you never click Connect. Next time you launch Companion, the picker opens directly on that card with a small "Welcome back" indicator. So if you spent a session inspecting Kit hardware and never plugged in, your next launch starts on Kit, not the default AirLeak card.
Pick the device you want and click Connect. Companion switches to the appropriate workspace for that device type.
What happens after you connect
The view changes based on what you connected:
- HID device → the HID dashboard fills the main window. The terminal becomes available in the sidebar.
- AirLeak device → the AirLeak workspace replaces the main view. Live data starts streaming immediately.
- Custom firmware → if you have a custom device profile configured, Companion uses your profile; otherwise it falls back to the generic terminal view.
What does not happen
A few things Companion deliberately does not do on first launch:
- No telemetry handshake. Companion never reports your install, your platform, or your usage to ZeroTrace.
- No automatic firmware update. Companion shows you when a firmware update exists but only flashes when you explicitly say so.
- No cloud session. Your devices, your sessions, your library — all stored locally.
- No account sign-in. Companion is free to install and use; nothing is gated behind authentication.
Next steps
Once your device is connected:
- HID → HID Dashboard.
- AirLeak → AirLeak workspace.
- Want to use the AI assistant? → AI Assistant (works with or without a connected device).