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.

Operation

1. 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.
2. Return to automatic mode: Click the tray icon → "Return to automatic mode."
3. Switch the secure DNS provider: Click the tray icon, hover over the DNS submenu, and click the provider you want to use.
4. If you lose connectivity: Click the tray icon → Recovery submenu → "Emergency Network Recovery."
5. 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.

Operation

1. Register the current network: Click "Register" on the "Currently connected network" card, choose a name and security level, then click "Save."
2. 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.
3. 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.

Operation

1. Isolate a development server's port: On the "Exposed ports & dev server isolation" card, select the port and click "Isolate" or "Block."
2. 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

Operation

1. Click the switch on the "USB / BadUSB defense" card to enable it.
2. 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.

Operation

1. Scan right now: On the "ClamAV on-demand scan" card, choose a folder and click "Start Scan."
2. Handle quarantined files: On the "Quarantine vault" card, select a file from the list and click "Restore" or "Delete permanently."
3. 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

1. Under the configuration card's "Backend," choose WireGuard or Tailscale.
2. For WireGuard, select a .conf file under "Import Configuration File." For Tailscale, click "Log In" and authenticate your account in the browser.
3. 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. 🔎 Security Activity Log

Lets you search and visualize, on a single screen, everything RoamSwitch has detected, notified, or acted on so far. It merges the contents of Chapter 14's "Incident Timeline" and Chapter 13's "Notifications" into one view, filterable by time range, category, severity, and keyword. This is different from Chapter 12's "Security Log Audit" (which audits OS-side logs such as journald) — this tab instead lets you look back at what RoamSwitch itself has already detected, notified, or decided.

Operation After narrowing down with the time range, category, and severity dropdowns and the keyword search field, click a specific time slot in the bar chart at the top of the screen to narrow the list down to just that slot's events. Click "Clear filter" to remove the narrowing.

16. 🔗 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.

17. 📦 Package CVE Scan

A broad vulnerability and supply-chain protection tab, covering everything from your OS package manager to per-language development packages.

On Ubuntu (20.04, 22.04, 24.04, 26.04), the OS package CVE scan uses Ubuntu's own data and matches by source package name and source version. It checks only high-severity CVEs (CVSS 7.0 or higher) that Ubuntu has already shipped a fix for. CVEs without a published fix, ones not yet assessed and ones Ubuntu has decided not to fix are not included, so "no findings" does not mean there are no known CVEs. The kernel is left to the existing kernel CVE data and is not part of this check. A fix that is only available through Ubuntu Pro (ESM) is marked with 🔒 and the note "This fix is only available through Ubuntu Pro (ESM)". On Ubuntu derivatives such as Linux Mint and Pop!_OS, and on releases that are not supported, the scan says that this Ubuntu is not covered by the CVE check. It does not fall back to the Debian data, to avoid false positives. The Ubuntu data is signed and is delivered only to Ubuntu machines (about 4 MB). A machine that does not have it yet fetches it in the next daily update and then checks for a newer version about every 30 days. Checks on Debian, Arch, RHEL-family and SUSE systems are unchanged.

Operation

1. Click "Start Scan" on either the "OS Package CVE Scan" or "Development Dependency CVE Scan" card.
2. When it finishes, the matching vulnerabilities are listed, each with a suggested fix (such as an update command).

18. 💎 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

1. Paste your license key into the license key field and click "Activate."
2. 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.

19. 🧰 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

1. Emergency recovery when you lose connectivity: Click the "Emergency Network Recovery" button, then choose "Recover" in the confirmation dialog.
2. 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). See the uninstall steps for the details.

20. 📖 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.

21. 🌐 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.

22. ℹ️ 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.

23. 🔄 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.

24. 🛟 Ransomware Recovery (Snapshots & File Restore)

In the "Ransomware Recovery" tab in the sidebar, for your home directory, safely extract just the files or folders you need from snapshots taken automatically before any damage. Your current files are never overwritten. (In the standard desktop edition, this is available from Linux 1.11.21.)

There are three kinds of snapshots. “Pre-damage” snapshots are taken automatically at a fixed interval (every 6 hours by default), regardless of any damage. “At detection” snapshots are always taken when ransomware-like behavior is detected. “Manual” snapshots are the ones you take yourself with the command.

When restoring, choose the “Pre-damage” snapshot marked “★ Recommended”. At detection: ⚠ Taken after detection, so it contains already-encrypted files. It is not a source for restoring to before the encryption (it preserves what was intact and serves as evidence).

Extracted files never overwrite your current files. They are placed in a separate folder (by default RoamSwitch-Recovered// inside the target folder).

Pre-damage snapshots are taken automatically every 6 hours by default (4 generations are kept on btrfs, 2 on LVM). You can change the interval with the command sudo roamswitch-ransomware-rollback config set --periodic-interval-secs <N> (0 disables it; otherwise 300 seconds or more). After a detection-time snapshot, pre-damage snapshots pause for 7 days so that already-encrypted data cannot push out the last clean generation. Snapshots at detection time are always taken, regardless of this setting.

Supported targets are btrfs and LVM. On a system without one, the following message is shown. Could not get the snapshot list (ransomware rollback is not installed, or there is no btrfs/LVM target).

Roll back everything (advanced, command only): sudo roamswitch-ransomware-rollback restore <ID>. Caution: the current state is overwritten with the selected snapshot's contents. Try "Restore Files" and "Restore a Folder" first. A detection-time snapshot is refused unless you add --accept-tampered.

It is also available from the command line (roamswitch-ransomware-rollback). See the CLI / headless operation page for details.

25. 🕸️ Web shell and injected-code detection (Web Rules)

Dedicated rules find PHP, JavaScript, JSP and ASP web shells, injected obfuscated code, PHP hidden in images and .htaccess abuse. On a machine where you develop web apps, your project folders are covered too. No setup is needed: files are checked automatically when they are written or opened. The rules ship with the product and are refreshed by the daily receive-only update. (From Linux 1.11.23.)

When something is found, a confirmation dialog ("Dangerous file detected") appears. It shows the file's name and location, with three buttons: "Later", "Allow (skip in future scans)" and "Move to Quarantine". Nothing happens to the file until you choose. "Move to Quarantine" moves it to the vault (you can restore it later in the Malware & Quarantine tab). If code you are developing is flagged, look at its contents before you choose. "Allow" removes that file from future checks.

To check whole folders, use roamswitch web-scan <folder>. The default is look-only: nothing is moved. The result shows the severity (CRITICAL / HIGH / MEDIUM), the rule name and a description. The exit status is 0 for no match and 2 for a critical or high match (handy in CI). --json prints JSON, and --no-default-excludes includes anything under tests/, fixtures/ and .git/, which are skipped by default because test code quotes the same constructs. roamswitch web-rules shows the rule version and state.

These are advanced settings. Put your own rules in /etc/roamswitch/rules.d/*.json (only files owned by root that others cannot write are read; a template is roamswitch web-rules example rules, and roamswitch web-rules validate <file> checks one). To call your own script on every detection, place an executable at /etc/roamswitch/hooks/post-detection (the hit is passed as JSON on standard input; a template is roamswitch web-rules example hook). The quarantine level and other options are set in /etc/roamswitch/web_rules.conf (roamswitch web-rules example conf).

Limits: only the first 256 KB (on write/execute) or 4 MB (scan) of a file is read, split-up names such as 'ev'.'al' are not followed, and no per-malware signatures are shipped because there are no real samples. If you suspect a false positive, choose "Allow" or exclude it with a rule of your own.

26. 🤖 AI Agent Setup Audit

This screen checks the instruction files and skills you give AI agents (Claude Code, Codex, Cursor, Gemini, OpenClaw and others), and OpenClaw's settings file, for risky content. Open "🤖 AI Agent Setup Audit" in the left menu and press "Run audit"; it is read-only. It looks at ~/.claude (CLAUDE.md, commands, agents, skills), ~/.codex, ~/.cursor/rules, ~/.gemini, ~/.agents and ~/.openclaw in your home folder, and CLAUDE.md, AGENTS.md, .cursorrules and similar files in the project folders registered in "Package CVE Scan". It makes no network connection, and neither file contents nor key or token values appear on screen or in the result.

It looks for instructions hidden in invisible Unicode characters, sentences such as "ignore previous instructions" or "do not tell the user", code that downloads a script and runs it as it is (curl … | sh), code that decodes a string and runs it, references to secret files (SSH keys, cloud credentials and the like) next to something that sends data out, compiled code inside a skill, files other users can write, and, for OpenClaw, authentication switched off, a token under 24 characters, a setting that allows every site, and the switches whose names start with dangerously. Anything inside an HTML comment, which disappears when the Markdown is rendered, is rated higher.

The result is split into "Severity: High" and "Medium", each with the file, the line number and the reason. A match means a person should read that line, not that it is malicious; a document that explains attacks, or an example sentence in a warning, can match. Files that could not be read are listed separately, and the screen never says "no findings" for them. On the command line it is roamswitch audit-agent-setup [FOLDER…] [--json]. An AI assistant gets the same result from the MCP tool audit_agent_setup.

27. 🔐 Blocking SSH brute force, and the intrusion path in notifications (no screen)

Only while SSH (sshd) is running on this machine, it watches failed SSH logins and blocks new connections from a source that fails repeatedly in a short time. It also cuts the SSH connections that source already had open, but never an authenticated session or a source on your exemption list. On a machine where sshd is not running it reads nothing and changes nothing. There is no settings screen: the 10 keys ssh_guard_* in ~/.config/roamswitch/config.json change it (see the settings table in CLI / headless operation). Notifications are desktop notifications and are kept in the history.

The sources currently blocked are listed with sudo roamswitch bans and lifted with sudo roamswitch unban <IP> (--all lifts every one). At the client's default protection levels inbound traffic is closed, so connections may not reach SSH at all, and then there is less for the blocking to do. When fail2ban or CrowdSec already guards sshd, RoamSwitch yields the blocking and only detects and notifies.

A notification about a tampered critical file (FIM) now names the process that made the change and the SSH login it belongs to (source, time, authentication method). A notification about access to a credential file carries it only when the process belongs to an SSH login. When it could not be checked, the notification says "The login path could not be determined" and never says it was not a login. To turn it off, write "fim_intrusion_context_enabled": false in config.json.