RoamSwitch for Linux Manual
This guide covers the desktop edition of RoamSwitch (tray icon + main window), walking through the tray menu and every tab of the main window in the exact order they appear. It assumes a GTK desktop environment (GNOME, KDE, XFCE, etc). For running a headless server, see the Server Edition Operations Manual.
1. About this manual
RoamSwitch for Linux runs as a ๐ก๏ธ icon in your desktop's system tray (notification area). Click the tray icon to open a menu, and from there you can open the main window for more detailed settings.
Many of the more advanced features carry a Pro label. This means the feature only becomes available once you purchase (or trial) RoamSwitch Pro. Anything without this label is free to use.
2. Tray menu
This is the menu that opens when you click the tray icon. Here it is from top to bottom.
| Item | Description |
|---|---|
| Status line | Shows your current protection status (e.g. "๐ Away Protection [level]"). Click it to open the main window. |
| ๐จ Release Air-Gap & Restore Network Conditional | Only appears while your network is under emergency isolation (Air-Gap) due to a serious detected threat. Release it manually once you've confirmed it's safe. |
| ๐ถ Wi-Fi / wired connection status | Shows the currently connected network name and security type, or the wired connection state (informational only, not clickable). |
| Restore radio Conditional | Only appears when a radio like Wi-Fi or Bluetooth has been blocked as a protective measure, letting you restore it manually. |
| Apply Lockdown / Balanced / Open now | Instantly applies one of three security levels to your current network with a single click. Lockdown is the strictest, Open is the most relaxed. |
| Return to automatic mode / clear override | Stops using a manually pinned level and returns to automatic detection based on your network. |
| Duration submenu | Choose how long a manually applied level should stay in effect: until next disconnect, 1 hour, 2 hours, 4 hours, for today, or until manually cleared โ six options in total. |
| DNS submenu | Toggle DNS threat protection on or off, and choose from four secure DNS providers: Quad9, Cloudflare Security, AdGuard DNS, and CleanBrowsing. |
| Recovery submenu | Lets you run "Emergency Network Recovery" (forcibly restore connectivity if you've lost it) or "Uninstall." |
| Launch at login | Toggles whether RoamSwitch automatically starts every time you log into your OS. We recommend leaving this on for continuous protection. |
| Language submenu | Switches the tray menu's display language. Besides "Match system language," there are 10 options total: Japanese, English, Simplified Chinese, Traditional Chinese, Korean, French, German, Spanish, Italian, and Portuguese. |
| Open main window | Opens the detailed settings screen covered from Chapter 3 onward. |
| Quit | Quits RoamSwitch. Automatic protection stops working while it's quit. |
Operation
- Switch the protection level right now: Click the tray icon, then click Lockdown, Balanced, or Open. From the duration list that appears next (until next disconnect / 1 hour / 2 hours / 4 hours / for today / until manually cleared), click how long you want it to stay in effect.
- Return to automatic mode: Click the tray icon โ "Return to automatic mode."
- Switch the secure DNS provider: Click the tray icon, hover over the DNS submenu, and click the provider you want to use.
- If you lose connectivity: Click the tray icon โ Recovery submenu โ "Emergency Network Recovery."
- Change the display language: Click the tray icon โ Language submenu, and click the language you want.
On smaller screens or with high DPI scaling, the Lockdown/Balanced/Open items may be grouped together into a single "Security Level" submenu instead (the content is the same either way).
3. Opening the main window
You can open the main window either from "Open main window" in the tray menu, or by clicking the status line. Unlike the Mac version, where each feature opens its own separate window, everything here lives in one large window with 19 tabs (sections) you switch between using the left sidebar. The chapters that follow walk through those tabs in exactly the order they appear in the sidebar.
4. ๐ Network Management
The very first tab in the sidebar. Handles registering the network you're currently on, and managing your list of registered networks.
| Card | Description |
|---|---|
| Currently connected network | Shows your current network name and a "Register" button for this location. If it's already registered, shows its current security level instead. |
| Manually switch security policy | The same feature as the Mac version's "Manual Override": temporarily ignores automatic detection and pins a chosen level. |
| Automatic sharing-service control | Automatically disables services like file sharing while you're on an untrusted network. |
| Registered networks list | Lists and lets you edit every network you've registered so far, along with each one's security level. |
Operation
- Register the current network: Click "Register" on the "Currently connected network" card, choose a name and security level, then click "Save."
- Edit or delete a registered network: In the "Registered networks" list, select the row and use the pencil icon to edit or the trash icon to delete.
- Pin a level temporarily: On the "Manually switch security policy" card, choose a level and duration, then click "Apply."
5. ๐ Security Diagnostic Suite
A comprehensive scoring tab for your Linux machine's security configuration. A score and title appear at the top, with a pass/fail checklist below. This is the Linux counterpart to the Mac version's "Mac Security Comprehensive Diagnostic." We recommend checking this tab periodically to make sure no red or yellow items remain.
Operation Items shown in red or yellow have a fix button next to them. Clicking it resolves most issues on the spot and updates the score automatically.
6. ๐ช Ports & DevIsolator
The largest tab of them all. It brings together everything related to network boundaries: guarding against exposed development-server ports, ARP anomaly detection, Sensor pairing, and vulnerability scanning.
| Card | Description |
|---|---|
| Exposed ports & dev server isolation | Lists ports open and reachable from outside โ like a dev server you forgot to shut down โ and manages isolating or blocking them. |
| Port & ARP anomaly auto-containment | Settings for automatically containing traffic when ARP spoofing or a suspicious port scan is detected. |
| Paired Sensors | Lists devices already linked with the separate "RoamSwitch Sensor" product. |
| Pair manually with a pairing code | Enter a pairing code issued by a Sensor to link a new one. |
| Sensor audit results | Review diagnostic results reported by paired Sensors. |
| Proof-based vulnerability scan status | Shows the results of a vulnerability scan that actually attempted to reach your open ports. |
Operation
- Isolate a development server's port: On the "Exposed ports & dev server isolation" card, select the port and click "Isolate" or "Block."
- Pair a Sensor: On the "Pair manually with a pairing code" card, enter the code issued by the Sensor and click "Link."
7. ๐ USB & BadUSB Guard
| Card | Description |
|---|---|
| USB / BadUSB defense | Enable or disable protection against "BadUSB" attacks, where a device disguises itself as a USB drive but acts as a keyboard to run unauthorized commands. |
| Connected USB & HID devices | Lists currently connected USB devices, keyboards, mice, and similar hardware. |
| Allowed USB devices (allowlist) | Register devices you've confirmed are safe, so only unrecognized, unregistered devices trigger a warning. |
Operation
- Click the switch on the "USB / BadUSB defense" card to enable it.
- From the "Connected USB & HID devices" list, select any device you'll keep using and click "Add to allowlist."
8. ๐ฆ Malware & Quarantine
Brings together ClamAV antivirus protection and Linux-specific low-level defenses: fanotify, entropy analysis, YARA rules, and no-exec enforcement.
| Card | Description |
|---|---|
| ClamAV definitions & engine status | Check when virus definitions were last updated and whether the engine is running. |
| Linux low-level advanced defense | Configures fanotify (real-time inspection the moment a file is accessed), entropy analysis (detecting ransomware-style encryption behavior), YARA rule matching, and enforced no-exec attributes, all in one place. |
| ClamAV on-demand scan | Manually scan a chosen folder right now. |
| Quarantine vault | Restore or permanently delete files that were quarantined after being flagged as malware. |
| Watched folders (web & email protection) | Configure which folders, such as Downloads, get auto-scanned whenever a new file appears. |
| Scan exclusions | Specify folders, like development directories, that should be excluded from scanning. |
Operation
- Scan right now: On the "ClamAV on-demand scan" card, choose a folder and click "Start Scan."
- Handle quarantined files: On the "Quarantine vault" card, select a file from the list and click "Restore" or "Delete permanently."
- Add a watched folder: On the "Watched folders" card, click "Add folder," choose somewhere like your Downloads folder, and click "Save."
9. ๐ก๏ธ DNS Threat Guard
Blocks name resolution at the DNS level for phishing sites and the command-and-control (C2) servers malware uses to talk to attackers. Choose a provider (such as Quad9) from the dropdown, and set "Enforcement Scope" to control which networks it applies to. This works together with the DNS submenu in the tray menu (Chapter 2).
Operation After turning the toggle on, choose a provider from the "Secure DNS Provider" dropdown, then set "Enforcement Scope" to control which networks it applies to.
10. ๐ VPN Tunnel Pro
Encrypts your traffic through a VPN on untrusted networks. The status card shows your current connection state, and the configuration card manages your connections (such as importing a WireGuard configuration). Like section 11.2 in the Mac manual, this protects against eavesdropping and tampering when you're on a network you don't trust.
Operation
- Under the configuration card's "Backend," choose WireGuard or Tailscale.
- For WireGuard, select a
.conffile under "Import Configuration File." For Tailscale, click "Log In" and authenticate your account in the browser. - Once configured, click "Connect." The VPN is active once the status card shows "Connected."
11. ๐ Secret & API Key Audit
An audit tool that scans your home directory and configuration files for sensitive data โ API keys, passwords, tokens โ that may have been accidentally left in plain text. Helps prevent developers from unintentionally leaving secrets behind in a repository or config file.
Operation Click "Start Scan" to begin the audit. When it finishes, the detected items (file path and type) are listed.
12. ๐ Security Log Audit
A tab for auditing and browsing security-related logs recorded by RoamSwitch and your Linux system. Lets you trace what was detected and how it was handled, in chronological order.
13. ๐ Notifications
A history of notifications RoamSwitch has shown over the past 7 days. Handy for checking back on a tray notification you might have missed.
14. ๐ Incident Timeline
Lets you review security events โ detection, response, resolution โ together in chronological order (an experimental feature). Useful when you want the big picture of what happened, rather than tracking down individual log entries.
15. ๐ Link Safety Audit
Combines link-protection settings with a manual check tool where you can paste a single URL to verify it on the spot. Corresponds to sections 9.5 and 9.6 in the Mac manual.
Operation To check a URL on the spot, paste it into the "Manual Check" card's input field and click "Check." A safety verdict appears within a few seconds.
16. ๐ฆ Package CVE Scan
A broad vulnerability and supply-chain protection tab, covering everything from your OS package manager to per-language development packages.
| Card | Description |
|---|---|
| OS package CVE scan | Cross-checks your distribution's package manager (dpkg, pacman, dnf, zypper, and others) against known vulnerabilities (CVEs). |
| Development dependency CVE scan | Cross-checks vulnerabilities in your development project's dependencies from npm, PyPI, crates.io, RubyGems, Packagist, Go, and Maven. |
| Dependency lockfile tamper monitoring Pro | Watches for unauthorized changes to lockfiles like package-lock.json. |
| Install script inventory Pro | Catalogs scripts that run during package installation, so you can review anything that looks suspicious. |
| Typosquat detection Pro | Detects fake packages with names deliberately similar to legitimate ones (typosquatting). |
| npm signature & provenance verification (opt-in) Pro | An additional check that verifies npm package signatures and provenance data to confirm nothing has been tampered with. |
Operation
- Click "Start Scan" on either the "OS Package CVE Scan" or "Development Dependency CVE Scan" card.
- When it finishes, the matching vulnerabilities are listed, each with a suggested fix (such as an update command).
17. ๐ Pro License
Lists everything included for free, business-oriented information for running on servers, VPS, cloud, or bare metal, and access to the Fleet panel for managing multiple machines at once. License activation for Pro also happens here.
Operation
- Paste your license key into the license key field and click "Activate."
- If you don't have a key yet, click "Purchase" to go through checkout. Once activation succeeds, this tab and the tray menu update to reflect it.
18. ๐งฐ Recovery & Uninstall
A tab bringing together emergency recovery (for when traffic has been accidentally blocked) and uninstallation โ the same functionality as the tray menu's "Recovery" submenu, with fuller explanations.
Operation
- Emergency recovery when you lose connectivity: Click the "Emergency Network Recovery" button, then choose "Recover" in the confirmation dialog.
- To uninstall: Follow the guidance in this tab, or run the command for your package format in a terminal (for example,
sudo apt purge roamswitch).
19. ๐ Help & Guide
The app's built-in help screen, covering everything from basic usage to supplementary notes on individual features. Use it alongside this web manual.
20. ๐ Language
Sets the main window's display language. The same languages are available here as in the tray menu's own language setting (Chapter 2).
Operation Choose a language from the dropdown, and the main window's display switches immediately.
21. โน๏ธ About RoamSwitch
Brings together version information, general settings, developer information, license, security policy, privacy policy, terms of service (EULA), disclaimer, and trademark/copyright notices โ the app's basic and legal information. If you're contacting support, check your version number here first.
22. ๐ Upgrade
Shows the status of automatic updates for the app itself, package update status, and threat-definition/scam-list update status. If you installed via your distribution's package manager, updates are normally kept current automatically alongside regular system updates.