ROAMSWITCH FOR MAC 1.10.7 · Last updated: 2026-09-28

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.

There is no "Preferences" window

Unlike most Mac apps, RoamSwitch has no tabbed "Preferences" window. Instead, you pick the feature you want to configure directly from the menu bar menu, and a small window dedicated to that feature opens. If you're wondering "where are the settings?", start by clicking the menu bar icon. Chapters 2 onward in this manual simply walk through that menu from top to bottom.

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

Click the menu bar 🛡️ icon and choose ⚠️ Approve Helper….
In the macOS dialog that appears, enter the username and password of an administrator account on this Mac.
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.

Item	Description
🔒 Isolated (full)	All network traffic is being blocked.
🔒 Isolated (degraded)	Only the minimum necessary traffic is allowed while suspicious traffic is blocked.
ℹ️ Why you're isolated & how to release…	Opens a screen explaining why isolation triggered and how to release it.
🔓 Release Air-Gap isolation	Manually releases isolation and restores network traffic once you've confirmed it's safe to do so.

Before you release it

Air-Gap is designed carefully to avoid false positives, so if it triggered, there's usually a reason. Check "ℹ️ Why you're isolated & how to release…" first to see why it fired, and think back over anything suspicious (like launching an unfamiliar app) before releasing it.

Operation

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.
If nothing seems out of the ordinary, choose 🔓 Release Air-Gap isolation from the same menu.
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

Option	Description
Register as "Home" (Trusted)	Registers this network at the most relaxed security level. Meant for your home Wi-Fi, used only by your family.
Register as "Work" (Standard Protection)	Registers this network at a medium security level. Meant for places like an office that you share with others.
Register as "Tethering" (Standard Protection)	Meant for connections like phone tethering: yours alone, but closer to a public network.
Register with custom name…	Lets you choose your own name and security level, so you can label it however fits — "Parents' house," "Satellite office," and so on.

Operation

While connected to the network you want to register, click the menu bar 🛡️ icon.
Hover over Register current network, then choose "Home," "Work," or "Tethering" from the submenu, or choose "Register with custom name…".
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

To change the security level: Click the menu bar 🛡️ icon → Current network: {registered name}, and click the level you want — it applies immediately.
To rename it: Below the divider in the same submenu, click "Rename…," type a new name, and click "Save."
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

Hover over the menu bar 🛡️ icon's Registered Networks (count).
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

Hover over the menu bar 🛡️ icon's Away-from-home default protection: {level}.
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

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.

Quick scan vs. custom scan

A quick scan checks the places malware tends to sneak into, like your Downloads folder and Desktop, in a short amount of time. If you want a thorough sweep of a specific folder, even if it takes longer, use a custom scan and point it at that folder.

Operation

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.
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."
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

In the Malware Protection submenu, click the "Web & Email Protection" row and turn the toggle on.
Open "📁 Watched Folders," click "Add Folder" to choose somewhere to monitor (such as Downloads), and click "Save" (your Downloads folder is included by default).
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

In the Malware Protection submenu, click the "DNS Threat Protection" row to turn the toggle on.
Hover over "Provider" and click the secure DNS service you want to use.
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

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

9.6 On-demand manual check tools

Item	Description
🔗 Check a Link Manually…	Paste a single URL you're curious about to check on the spot whether it's a phishing or otherwise malicious site.
🔑 Audit Secrets & API Key Leaks Manually…	Scans your Mac for API keys, passwords, and other sensitive data that may have been accidentally saved in plain text.
📦 Cross-Check Package CVEs (Homebrew)…	Checks packages installed via Homebrew against known vulnerabilities (CVEs).

Operation

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.
Audit secrets & API key leaks manually: Choosing this item starts a scan; when it finishes, the detected items (file path and type) are listed.
Cross-check package CVEs: Choosing this item enumerates your installed Homebrew packages and lists the results of checking them against known vulnerabilities.

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. Unless you have a specific reason not to, we recommend Pro users leave all of these enabled.

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.

Item	Description
Auto-block network on XProtect malware detection Pro	Automatically blocks network traffic the instant XProtect detects malware.
Monitor new auto-launch registrations Pro	Watches for new LaunchAgent/LaunchDaemon auto-start registrations, detecting suspicious persistence (malware trying to stick around).
Auto-block on suspicious Terminal commands (ClickFix defense) Pro	Detects and blocks "ClickFix"-style attacks, where a fake error screen tricks you into pasting a malicious command into Terminal.
Detect Docker privileged containers & docker.sock mounts Pro	Detects dangerous configurations that make container escapes easier, such as privileged-mode launches or an accidentally mounted docker.sock.
🐤 Ransomware canary file detection Pro	Plants "canary files" in conspicuous locations, and treats any encryption or tampering of them as an immediate ransomware signal.
🔐 Generic ransomware detection (entropy analysis) Pro	Statistically detects file contents rapidly turning into near-random data — a strong sign of encryption. Catches new ransomware strains that skip past canary files.
🍯 Credential honeytokens Pro	Plants fake "decoy" credentials, and treats any attempt to read them as evidence that an intruder is present.
🔑 Browser credential access monitoring Pro	Monitors for suspicious access to passwords and cookies stored in your browser — a classic behavior of information-stealing malware.
🗂 Ransomware Recovery… Pro	Opens a step-by-step window for recovering from Time Machine or another backup after a ransomware incident.
🧾 Process Execution Recording… Pro	Records a history of launched processes so you can investigate what ran after an incident.
🔔 Automatic log auditing (learns new patterns & frequency anomalies) Pro	Periodically learns from system logs and automatically detects and notifies you of unusual patterns or frequency anomalies.
🔔 Periodic monitoring of critical system file tampering Pro	Periodically checks whether important OS files have been modified (FIM: File Integrity Monitoring).
🔔 Periodic monitoring of dependency lockfile tampering Pro	Watches for unauthorized changes to lockfiles like package-lock.json in your development projects — a defense against supply-chain attacks.

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.

Item	Description
🚨 Ransomware Protection Simulation	Simulates the canary-file and entropy-detection mechanisms using a harmless test file.
🚨 Malware-triggered Air-Gap Simulation	Lets you walk through the full flow from malware detection to Air-Gap isolation, with no real harm done.
⚠️ Docker Risk Detection Simulation	Confirms that the privileged-container detection notification arrives correctly.

Operation

Choose the simulation you want to try from the Malware Protection submenu.
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.

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.

Item	Description
📊 Open Full Diagnostic Report…	Opens a report screen summarizing every check item and how to fix anything that needs attention.
📜 Mac Security Log Audit…	Review the log of security events detected and recorded so far.
🔔 Notification History…	A list of notifications RoamSwitch has shown you in the past.
Re-run Diagnostic Now	Runs the diagnostic again on the spot and refreshes it to the latest results.

Operation

After reviewing your settings, click "Re-run Diagnostic Now" in the submenu to refresh the score on the spot.
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.

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.

Operation

If you want to block manually while an attack is being detected, click "Block Everything Now" in the Ports & Device Monitoring submenu.
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."

Backend	Characteristics
WireGuard	Uses a WireGuard configuration you provide yourself. You can connect and disconnect, check connection status (handshake), enable a kill switch (a safety net that cuts all traffic if the VPN drops), and import or delete configuration files.
Tailscale	Uses your Tailscale account's mesh network. You can choose an Exit Node, toggle the kill switch, and connect or disconnect.

Operation

Go to Ports & Device Monitoring submenu → "VPN Tunnel" → "Backend," and choose whether to use WireGuard or Tailscale.
For WireGuard: Choose "Import Configuration File…" and select the .conf file you prepared in advance. Once imported, click "Connect" to activate the VPN immediately.
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."
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.

Item	Description
Auto-block unknown listening ports Pro	Automatically blocks external access whenever an unfamiliar new port opens up.
Inbound port scan detection Pro	Detects "port scanning," the reconnaissance attackers do before an attack.
Proof-based vulnerability scan (active reachability check)	Actually attempts to reach open ports to verify whether they're really accessible from outside.
Export proof-based scan log as CSV Pro	Exports scan results to a CSV file for record-keeping or reporting.
Show proof-based scan status Pro	Check a summary of the most recent scan results on the spot.
RoamSwitch Sensor Pairing…	Links this Mac with a separate product, "RoamSwitch Sensor," installed on a server or IoT device.

Operation

To check which ports are open, hover over "Externally Exposed Ports (count)" in the Ports & Device Monitoring submenu.
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.

Item	Description
Unauthorized USB / BadUSB physical port guard Pro	Detects and warns about the connection of any USB device that hasn't been explicitly allowed.
Auto-block unauthorized USB storage Pro	Automatically disables any USB storage device that isn't on your allowlist.
USB / BadUSB Guard Settings…	Opens the settings window where you register and manage allowed devices.

Operation

Open "USB / BadUSB Guard Settings…," select any device you'll keep using from the list, and click "Add to allowlist."
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.

Duration	Description
Until next network disconnect (recommended)	Automatically clears when you disconnect from Wi-Fi or move to a different network. There's no risk of forgetting to switch back — the safest choice.
For 1 hour only	Automatically returns to automatic mode after 1 hour.
For 4 hours only	Automatically returns to automatic mode after 4 hours.
Keep until manually cleared	Stays in effect until you select "Return to automatic" yourself. Be careful not to forget to switch it back.

Operation

Hover over Manual Override in the menu bar 🛡️ icon's menu.
Click the security level you want to pin.
From the duration list that appears next, click how long you want to keep it — it applies immediately.
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

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

Item	Description
Help & Guide…	Opens the app's built-in help screen. Use it alongside this web manual.
About RoamSwitch…	Shows basic app information, such as the version number and developer. Useful for checking your version number before contacting support.
Check for Upgrade…	Checks on the spot for whether a newer version is available.

17. Recovery & Uninstall

Item	Description
🆘 Emergency Network Recovery…	Forcibly restores network connectivity if you've been accidentally left isolated or blocked and can no longer communicate. A last resort for "I can't get online anymore."
🗑 Uninstall RoamSwitch…	Completely and properly removes RoamSwitch itself, its helper, and related files — including support components that would otherwise be left behind if you just dragged the app to the Trash in Finder.

Dragging it to the Trash in Finder isn't enough

Because RoamSwitch involves a helper that runs with administrator privileges and a login item, simply trashing the app leaves some components behind. If you want to remove RoamSwitch, always use this "Uninstall…" option.

Operation

Emergency recovery when you lose connectivity: Click the menu bar 🛡️ icon → "🧰 Recovery & Uninstall" → "🆘 Emergency Network Recovery…," then choose "Recover" in the confirmation dialog.
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.

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.

← Setup Guide Go to Linux Manual →