RoamSwitch for Mac Manual

This guide walks through every item in the menu bar menu, in the exact order it appears. Even if this is your first time using RoamSwitch, you can follow along by opening the menu in this same order.

1. About this manual

RoamSwitch is an app that lives in your Mac's menu bar as a 🛡️ icon. Unlike most apps that you open from the Dock, you don't need to keep a window open at all. Just click the icon in the top-right of your screen, and a menu appears with options relevant to your current situation.

The menu isn't fixed. Which items appear depends on the app's current state. For example, "Approve Helper" only shows up while the helper hasn't been approved yet, and disappears once it has. Likewise, "Release Air-Gap isolation" only appears while isolation is actually active. Throughout this manual, items that appear conditionally are marked with a Conditional label.

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. Menu bar icon and status line

The very top of the menu shows a one-line summary of your current protection status, such as 🛡️ Protected on trusted network, with an emoji and a short phrase so you can tell the current state at a glance. Clicking this line opens a screen with a more detailed explanation of the current status.

The icon itself also changes appearance depending on the state (for example, it switches to a warning color while isolated). Just glancing at the menu bar icon gives you a rough sense of "how protected am I right now."

3. Approving the Helper (first run only) Conditional

To actually block network traffic or toggle the firewall, RoamSwitch relies on a small companion program called the "Helper" that runs with administrator privileges. Right after installation, while this helper hasn't been approved yet, an item labeled ⚠️ Approve Helper… appears near the top of the menu.

Clicking it prompts you for your macOS administrator password. Once approved, this item disappears for good, and every protection feature starts working automatically from then on. Until you complete this approval, RoamSwitch cannot actually block network traffic. Make sure to finish this step as part of your initial setup.

Operation

1. Click the menu bar 🛡️ icon and choose ⚠️ Approve Helper….
2. In the macOS dialog that appears, enter the username and password of an administrator account on this Mac.
3. Click "Modify Settings." Once the dialog closes and the item disappears from the menu, approval is complete.

4. Air-Gap isolation: what it shows and how to release it Conditional

"Air-Gap" is an emergency defense feature that physically cuts your Mac off from the network when RoamSwitch detects a serious threat, such as malware or ARP spoofing. While it's active, the top of the menu shows the type of isolation (full isolation / degraded mode) and, if known, the reason it triggered.

Operation

1. Click the menu bar 🛡️ icon and choose ℹ️ Why you're isolated & how to release…, found below the isolation status row (🔒 Isolated…), to check why it triggered.
2. If nothing seems out of the ordinary, choose 🔓 Release Air-Gap isolation from the same menu.
3. Choose "Release" in the confirmation dialog, and network traffic is restored immediately.

5. Wi-Fi connection info Conditional

While connected to Wi-Fi, a single line shows the network name (SSID) and encryption type (such as WPA3). Clicking it reveals more detail, including signal strength and frequency band. This line doesn't appear if you're only connected over wired Ethernet.

6. Registering and switching the current network

RoamSwitch's core idea is "go easy on trusted places like home or work, and lock things down on unfamiliar networks." To make that possible, you register the network you're currently on once, so RoamSwitch can automatically switch to the right security level the next time you return there.

If you're on a network you haven't registered yet

Operation

1. While connected to the network you want to register, click the menu bar 🛡️ icon.
2. Hover over Register current network, then choose "Home," "Work," or "Tethering" from the submenu, or choose "Register with custom name…".
3. If you chose "Register with custom name…," type a name of your choosing into the field that appears, choose a security level, and click "Register."

If you're on an already-registered network

The submenu lists the security levels you can set for this network (Trusted, Standard Protection, etc.) as radio buttons, with a checkmark next to the one currently in effect. Click any level to switch to it right away. Below the divider you'll find "Rename…" and "Unregister," for renaming the network or removing its registration entirely.

Operation

1. To change the security level: Click the menu bar 🛡️ icon → Current network: {registered name}, and click the level you want — it applies immediately.
2. To rename it: Below the divider in the same submenu, click "Rename…," type a new name, and click "Save."
3. To unregister it: Click "Unregister" in the same submenu. The next time you connect to this network, it's treated as unregistered and the away-from-home default protection (Chapter 8) applies.

7. Managing registered networks

Every network you've registered so far appears in this submenu. Each item is shown as {registered name} [{security level}] ({partial MAC address}), followed by the same security-level switching, rename, and unregister options as in Chapter 6. Use this when you want to review networks you registered while away from home, even if you're not near them right now. If you haven't registered anything yet, an empty state is shown instead.

Operation

1. Hover over the menu bar 🛡️ icon's Registered Networks (count).
2. Hover further over the network you want to review, and the same security-level list, "Rename…," and "Unregister" from Chapter 6 appear — choose whichever action you need.

8. Away-from-home default protection

This is the security level applied automatically whenever you connect to a network you've never registered before — a café, a train station, an airport, and so on. Choose from the submenu to change this default level. Because you can never be too careful on an unfamiliar network, the strictest level is selected by default. We recommend not lowering it unless you have a good reason to.

Operation

1. Hover over the menu bar 🛡️ icon's Away-from-home default protection: {level}.
2. Click the security level you want as the new default from the submenu that opens.

9. Malware Protection (XProtect & ClamAV)

This is the largest submenu in RoamSwitch. It gathers everything related to malware and unauthorized access: macOS's built-in XProtect, the free ClamAV antivirus engine, download scanning for web and email, DNS-level threat blocking, phishing link detection, and a long list of Pro-tier monitoring features. We'll go through it from top to bottom.

9.1 Apple XProtect

Shows the current version and status of XProtect, the malware detection engine built into macOS. "Check XProtect Status…" gives you the details, and "Diagnose File Safety…" runs a quick check on an individual file. RoamSwitch isn't adding anything here — this item simply surfaces protection that's already built into your Mac.

Operation

1. To check an individual file: Choose "Diagnose File Safety…" from the Malware Protection submenu, then either drag a file from Finder into the window that opens, or click "Choose File" to pick one.

9.2 ClamAV (Free Antivirus)

ClamAV is a free, open-source antivirus engine. When it's installed, this submenu lets you run a "Quick Scan Now," a "Custom Scan (choose a folder)," "Update Virus Definitions," and manage the "Quarantine." If it isn't installed yet, you'll see a prompt to install it instead.

Operation

1. To run a scan: Malware Protection submenu → ClamAV → choose "Quick Scan Now," or choose "Custom Scan…" and specify a folder. You can watch progress in the menu bar icon or the scan window, and you'll get a notification when it finishes.
2. To handle a quarantined file: From the same submenu, open "Quarantine," select a file from the list, and choose "Restore" (to put it back if it was a false positive) or "Delete Permanently."
3. To update virus definitions: From the same submenu, click "Update Virus Definitions." The latest definitions are fetched over the internet.

9.3 Web & Email Protection (Automatic Download Scanning) Pro

Automatically runs a virus scan every time a new file shows up in a folder you're monitoring, such as your Downloads folder. That means files get checked the moment you download them from a browser or save an email attachment, before you ever open them. Toggle it on or off, use "📁 Watched Folders" to add or edit which folders are monitored, and open the quarantine manager to review files that were quarantined based on scan results. While enabled, recent scan history is also shown.

Operation

1. In the Malware Protection submenu, check the "Web & Email Protection" row. It is already on once Pro is activated. If you turned it off, click the row to turn the toggle on.
2. Open "📁 Watched Folders," click "Add Folder" to choose somewhere to monitor (such as Downloads), and click "Save" (your Downloads folder is included by default).
3. From then on, any new file that appears in that folder is scanned automatically. If something is detected, you get a notification and the file moves to quarantine.

9.4 DNS Threat Protection (Malicious Sites & C2 Blocking) Pro

Blocks name resolution at the DNS level for dangerous domains, such as phishing sites or the "C2 (command-and-control)" servers malware uses to talk to attackers. After enabling the toggle, choose which secure DNS service to use under "Provider," and which networks it applies to under "Enforcement Policy." While enabled, the bottom of the menu shows whether secure DNS is actually being applied right now, or excluded because you're on a trusted network.

Operation

1. In the Malware Protection submenu, check the "DNS Threat Protection" row. It is already on once Pro is activated. If you turned it off, click the row to turn the toggle on.
2. Hover over "Provider" and click the secure DNS service you want to use.
3. Hover over "Enforcement Policy" and choose which networks it applies to (all networks, untrusted networks only, etc.).

9.5 Link Protection (Phishing Connection Detection) Pro

Checks links you're about to click, and connections apps are attempting to make, against a list of known phishing sites in real time, warning you if there's a match. Choose the operating mode from the submenu, check how up-to-date the phishing feed is, and toggle automatic feed updates on or off. While enabled, the menu also shows which mechanism (browser extension, network layer, etc.) is actually doing the checking.

Operation

1. In the Malware Protection submenu, hover over "Link Protection" and click an operating mode (notify only, auto-block, etc.).
2. Click the "Auto-Update" row to turn automatic phishing-feed updates on or off.

9.6 On-demand manual check tools

Operation

1. Check a link manually: Choosing this item opens an input field — paste the URL you want checked and click "Check." A safety verdict appears within a few seconds.
2. Audit secrets & API key leaks manually: Choosing this item starts a scan; when it finishes, the detected items (file path and type) are listed.
3. Cross-check package CVEs: Choosing this item enumerates your installed Homebrew packages and lists the results of checking them against known vulnerabilities.
4. Audit AI agent instruction files: choosing this item starts the check and lists the findings as cards, each with "Risk: High" or "Risk: Medium", the file and the line number. A match means a person should read that line, not that it is malicious. "Show in Finder" opens the file.

9.7 Always-on monitoring toggles

From here on, these are individual monitoring features that run continuously in the background, toggled on and off with a checkmark. They're listed in the exact order they appear. When Pro is activated, ransomware detection, credential honeytokens, the scheduled log audit, tamper monitoring of critical files and lockfiles, XProtect-linked auto-isolation and similar guards turn on by themselves. "SSH brute-force detection and blocking" in the Ports & Device Monitoring submenu (section 11.3) also turns on by itself when Pro is activated; it works only while Remote Login is on. ClickFix protection, Docker detection, browser credential-access watch and the process-execution recorder are off by default, because they can get in the way of normal use or need extra permissions. Unless you have a specific reason, leave the ones that are on as they are and turn on only what you need.

Operation For any of these, just click the corresponding row in the Malware Protection submenu to toggle it on or off (a checkmark shows the current state). "Ransomware Recovery…" and "Process Execution Recording…" open a dedicated window instead of toggling.

9.8 Test simulations

Harmless mock tests that let you safely verify "am I actually protected." Without generating any real threat, you can simulate the full flow — detection, notification, and (where applicable) automatic blocking — right on the spot. Great for checking things right after setup, or as a periodic health check.

Operation

1. Choose the simulation you want to try from the Malware Protection submenu.
2. If a confirmation dialog appears, choose "Run." Within a few seconds to a minute, you should get a notification in the same format as a real detection — that means it's working correctly.

9.9 Web shell detection rules (Web Rules)

For Macs used for web development, this finds PHP, JavaScript, JSP and ASP web shells, injected code, PHP hidden in images and .htaccess abuse (from Mac 1.11.11). It covers ~/Sites, MAMP, Herd, Local, /Library/WebServer/Documents, the project folders registered for package-CVE scanning, and the folders that Web & Mail Protection already watches (such as Downloads). It works without ClamAV.

Open the settings from the menu bar 🛡️ icon → Malware Protection → "Web shell detection rule settings…". The window shows the rule set version and count, "Check development web folders now", buttons that open the rules and hooks folders, "Automatic quarantine level", the account-response switch, and a list of files that were detected but left in place.

Only "critical" findings are quarantined by default. A serious detection (such as a one-line web shell like eval($_POST[...])) is moved to the vault and you are notified (you can restore it from "Manage Quarantined Files"). A lower "high" detection leaves the file alone and only produces a notification and an entry in the list in this window, where you can "Show in Finder", choose "do not detect again" or clear the list. This default keeps a false positive from moving a file you are working on. The level can be "do not quarantine", "critical only" or "critical and high". The list of files set to "do not detect again" is separate from the ClamAV exclusions.

When it checks: folders that are already watched, such as Downloads, are checked right after a write. Development web folders are checked once a day and with "Check development web folders now". The daily check does not enter node_modules or .git because that takes too long (a check of a folder you pick does enter node_modules). The Mac cannot stop anything before it runs: all detection is after the fact.

Advanced: put your own rules in the folder opened by "Open rules folder" (~/Library/Application Support/RoamSwitch/rules.d; only files owned by root or you that others cannot write are read). To call your own script on every detection, place an executable named post-detection in the folder opened by "Open hooks folder" (~/Library/Application Support/RoamSwitch/hooks); the hit is passed as JSON on standard input and it is stopped after 30 seconds. The account response ("On detection, disable the login shell of the file's owner") is off by default. Turning it on needs the administrator password and it acts on the owner of a quarantined file. It never touches the logged-in user (including you, using this Mac), root, or UIDs below 501. A disabled account can be restored from this window.

10. Mac Security Comprehensive Diagnostic

A comprehensive scoring feature for your Mac's overall security posture. The menu title itself shows "passing/total ・ score" in real time, so you can gauge your health at a glance without even opening the menu. Opening the submenu shows a pass/fail list for each individual check.

Operation

1. After reviewing your settings, click "Re-run Diagnostic Now" in the submenu to refresh the score on the spot.
2. To see what needs attention, choose "📊 Open Full Diagnostic Report…" and review the red and yellow items in the window that opens. Most items include a button to fix them right there.

10.1 Security Activity Log

Unifies the containment incident timeline (ARP spoofing detection, ransomware bait file detection, XProtect-linked Air-Gap, unknown-port auto-block, and more) with confirmed malware detections from email attachments into one screen, so you can search by keyword, filter by category or severity, and drill down via a time-series chart.

The neighboring "📜 Mac Security Log Audit…" covers macOS's own Unified Logging (sudo, SSH, Gatekeeper, XProtect, and more); this screen instead searches only RoamSwitch's own containment decisions in one place.

Operation

1. Click the 🛡️ menu bar icon → "Comprehensive Mac Security Diagnostics" → "📈 Security Activity Log…".
2. Choose a category, severity, and time range at the top, and type a keyword into the search field if needed.
3. Click a bar in the chart to narrow the list to that time window. Click it again to clear the filter.

11. Ports & Device Monitoring

This section covers monitoring your Mac's "boundary with the outside world" — from the network itself (ARP spoofing, VPN, open ports) to physical devices connected to it (USB, Bluetooth).

11.1 ARP Spoofing Detection

Detects "ARP spoofing" attacks, where another device on the same network tries to impersonate you and intercept your traffic. The current status is shown in a single line, and "Block Everything Now" appears there if an attack is being detected. "Auto-block" and "Pin gateway ARP/NDP (preventive)" are both toggles — the latter is a preventive measure on untrusted networks that makes the attack itself harder to pull off in the first place. When Pro is activated, "Auto-block" is on by default, while "Pin gateway ARP/NDP (preventive)" is off by default.

Operation

1. If you want to block manually while an attack is being detected, click "Block Everything Now" in the Ports & Device Monitoring submenu.
2. Click "Auto-block" or "Pin gateway ARP/NDP (preventive)" to toggle either one on or off.

11.2 VPN Tunnel (MITM Protection on Untrusted Networks) Pro

Encrypts your traffic through a VPN whenever you're on an untrusted network, like a café or airport. Start by picking WireGuard or Tailscale under "Backend."

Operation

1. Go to Ports & Device Monitoring submenu → "VPN Tunnel" → "Backend," and choose whether to use WireGuard or Tailscale.
2. For WireGuard: Choose "Import Configuration File…" and select the .conf file you prepared in advance. Once imported, click "Connect" to activate the VPN immediately.
3. For Tailscale: Choose "Connect" to open Tailscale's login screen in your browser, then log in with your account and authorize it. After that, you can choose where to route through under "Exit Node."
4. For either backend, click the "Kill Switch" row to toggle it on or off. With it on, if the VPN connection drops unexpectedly, all traffic stops too, preventing your raw traffic from leaking out.

11.3 Externally Exposed Ports

Lists ports on your Mac that are open and reachable from outside — such as a development server you forgot to shut down — along with your current firewall status. A dev port left open by accident is a classic hole attackers look for, so we recommend checking this regularly to make sure nothing was left open.

Operation

1. To check which ports are open, hover over "Externally Exposed Ports (count)" in the Ports & Device Monitoring submenu.
2. Choosing "RoamSwitch Sensor Pairing…" opens an input field — enter the pairing code shown on the Sensor's screen and click "Link."

11.4 Connected USB Devices / USB & BadUSB Guard

Lists currently connected USB devices. Below that are protections against "BadUSB" attacks, where a device disguises itself as a USB drive but actually acts as a keyboard, typing commands without your permission.

Operation

1. Open "USB / BadUSB Guard Settings…," select any device you'll keep using from the list, and click "Add to allowlist."
2. Once that's set up, click "Unauthorized USB / BadUSB physical port guard" and "Auto-block unauthorized USB storage" in the Ports & Device Monitoring submenu to turn each on.

11.5 Bluetooth Auto-off

A toggle that automatically turns off Bluetooth at appropriate moments, such as while you're on an untrusted network. It cuts down on the opportunity for unauthorized Bluetooth connections at close range. What's displayed here depends on your Bluetooth state and hardware support.

Operation Click the corresponding row in the Ports & Device Monitoring submenu to toggle it on or off.

12. Manual Override

Normally RoamSwitch switches security levels automatically based on the network you're connected to, but this feature is for when you want to pin it to a specific level "just for now." Selecting "Return to automatic" at the top switches you back to automatic mode at any time. Below that, each security level is listed, and choosing one asks you how long you want to keep that setting in effect.

Operation

1. Hover over Manual Override in the menu bar 🛡️ icon's menu.
2. Click the security level you want to pin.
3. From the duration list that appears next, click how long you want to keep it — it applies immediately.
4. Whenever you want to return to automatic mode, click "Return to automatic" from the same place at any time.

13. RoamSwitch Pro

If you haven't purchased Pro yet, you'll see "💎 Activate / Purchase Pro…" — clicking it opens the license activation screen (which includes a path to purchase). If Pro is already active, this changes to "💎 RoamSwitch Pro (Active)," and clicking it lets you check your current license status. Once you activate a license here, all the Pro features described in Chapters 9 and 11 become available at once.

Operation

1. If you haven't purchased yet: Click the menu bar 🛡️ icon → "💎 Activate / Purchase Pro…" to open a screen you can use to purchase (or trial) it.
2. If you already have a license key: Paste your key into the license key field on the same screen and click "Activate." Once activation succeeds, the menu changes to show "💎 RoamSwitch Pro (Active)."

14. Launch at Login

A toggle for whether RoamSwitch automatically launches every time your Mac restarts or you log in. When checked, it starts automatically at login. For continuous protection, we strongly recommend leaving this on.

15. Language

Lets you choose RoamSwitch's own display language from the submenu's radio buttons. This is independent of your macOS system language — you can switch RoamSwitch's language on its own.

Operation Click a language in the submenu, and the menus and windows switch immediately.

16. Help, About & Update Check

17. Recovery & Uninstall

Operation

1. Emergency recovery when you lose connectivity: Click the menu bar 🛡️ icon → "🧰 Recovery & Uninstall" → "🆘 Emergency Network Recovery…," then choose "Recover" in the confirmation dialog.
2. To uninstall: From the same submenu, click "🗑 Uninstall RoamSwitch…." Enter your administrator password if prompted, then choose "Uninstall" in the confirmation dialog to remove the app, helper, and related files entirely. See the uninstall steps for the details.

18. Quit

Quits RoamSwitch entirely. Keep in mind that while it's quit, automatic network detection and protection features stop working. If you only want to pause things temporarily, consider using "Manual Override" from Chapter 12 to pin a specific level instead of quitting.