VMware Fusion (macOS)

This guide covers deploying CICADA IR on VMware Fusion for macOS, including both Intel and Apple Silicon Macs. VMware Fusion Pro is available as a free personal-use licence from Broadcom.

Prerequisites

  • macOS 13 (Ventura) or later
  • VMware Fusion 13+ (Intel) or Fusion 13.5+ (Apple Silicon)
  • At least 8 GB of free RAM (16 GB total recommended)
  • 40 GB of free disk space
  • The CICADA IR VM image:
    • Intel Macs: cicada-ir-<version>-x64.ova
    • Apple Silicon Macs (M1/M2/M3/M4): cicada-ir-<version>-arm64.vmwarevm.tar.gz — native ARM build, no binary translation needed

Apple Silicon note

CICADA IR provides a native ARM64 build for Apple Silicon Macs. Download the arm64.vmwarevm.tar.gz image from your download link — this runs natively on M1/M2/M3/M4 without binary translation. Extract the .tar.gz and double-click the .vmwarevm bundle to open it in Fusion.

Do not use the x64 OVA on Apple Silicon — it will run under binary translation and be significantly slower.

Installing VMware Fusion

If you don't already have Fusion installed:

  1. Download VMware Fusion from the VMware website
  2. Open the downloaded .dmg and drag VMware Fusion to Applications
  3. Launch Fusion and complete the initial setup
  4. When prompted for a licence key, select I want to try VMware Fusion Pro for free for personal use, or enter your commercial licence key
  5. Grant the required macOS permissions when prompted:
    • System Settings > Privacy & Security > Full Disk Access — add VMware Fusion
    • Approve the kernel extension if prompted (Intel Macs)

Import the CICADA IR VM

Method 1: GUI import (recommended)

  1. Open VMware Fusion
  2. Go to File > Import (or drag the .ova file onto the Fusion window)
  3. Browse to the CICADA IR .ova file and click Open
  4. Fusion will display the import settings. Click Customize Settings before importing to adjust resources:
    • Processors & Memory: Set to 4 CPU cores and 8192 MB RAM
    • Hard Disk: Leave as imported (the OVA includes the disk)
  5. Choose a save location (default is ~/Virtual Machines/)
  6. Click Save to begin the import

Method 2: OVFTool CLI import

# OVFTool is included with Fusion at:
# /Applications/VMware Fusion.app/Contents/Library/VMware OVF Tool/ovftool

# Create an alias for convenience
alias ovftool="/Applications/VMware\ Fusion.app/Contents/Library/VMware\ OVF\ Tool/ovftool"

# Import the OVA to a VMX
ovftool --name="cicada-ir" cicada-ir-latest.ova ~/Virtual\ Machines/cicada-ir.vmwarevm

# The VM is now available in the Fusion library

Configure networking

CICADA IR needs network access to communicate with your data sources and (optionally) cloud services. Choose the network mode that fits your environment:

Bridged networking (recommended)

Bridged mode gives the VM its own IP address on your local network, making it accessible from other machines on the same network.

  1. Select the CICADA IR VM in the Fusion library
  2. Go to Virtual Machine > Settings (or press ⌘E)
  3. Click Network Adapter
  4. Select Bridged Networking and choose:
    • Autodetect — Fusion picks the active interface (usually Wi-Fi or Ethernet)
    • Or select a specific interface (e.g., Wi-Fi or Ethernet)

NAT networking

NAT mode shares the Mac's IP address. The VM can reach the internet but other machines on your network cannot reach the VM directly (useful for testing).

  1. Go to Network Adapter settings
  2. Select Share with my Mac (NAT)

To access the CICADA IR web UI from your Mac when using NAT, you will need to set up port forwarding:

# In Fusion: Virtual Machine > Settings > Network Adapter > Advanced
# Or edit the NAT configuration:
# /Library/Preferences/VMware Fusion/vmnet8/nat.conf

# Add under [incomingtcp]:
# 8443 = <vm-ip>:443

Then access CICADA IR at https://localhost:8443.

Start the VM

  1. Select the CICADA IR VM in the library
  2. Click the Play button (or press ⌘R)
  3. If prompted about the virtual machine being moved or copied, select I Copied It
  4. Wait 1–2 minutes for all CICADA IR services to start

Find the VM's IP address

From the Fusion VM console, log in with the cicada-admin user and run:

ip addr show | grep "inet "

# Or more specifically:
ip -4 addr show ens160 | grep inet

You can also find the IP from your Mac terminal:

# List all DHCP leases issued by Fusion's NAT
cat /var/db/dhcpd_leases

# Or for bridged mode, check your router's DHCP table
# Or use arp scan:
arp -a | grep vmware

Access the web interface

Open your browser and navigate to:

https://<vm-ip-address>

Accept the self-signed certificate warning. For production use, replace the certificate (see TLS Certificates).

Headless operation

To run CICADA IR in the background without the Fusion GUI window:

# Start the VM headless using vmrun
/Applications/VMware\ Fusion.app/Contents/Library/vmrun start \
  ~/Virtual\ Machines/cicada-ir.vmwarevm/cicada-ir.vmx nogui

# Check if the VM is running
/Applications/VMware\ Fusion.app/Contents/Library/vmrun list

# Stop the VM gracefully
/Applications/VMware\ Fusion.app/Contents/Library/vmrun stop \
  ~/Virtual\ Machines/cicada-ir.vmwarevm/cicada-ir.vmx soft

Auto-start on macOS login

To start the CICADA IR VM automatically when you log in to your Mac, create a Launch Agent:

cat > ~/Library/LaunchAgents/com.cicada-ir.autostart.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.cicada-ir.autostart</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Applications/VMware Fusion.app/Contents/Library/vmrun</string>
    <string>start</string>
    <string>/Users/YOUR_USERNAME/Virtual Machines/cicada-ir.vmwarevm/cicada-ir.vmx</string>
    <string>nogui</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>
EOF

# Load the agent
launchctl load ~/Library/LaunchAgents/com.cicada-ir.autostart.plist

Replace YOUR_USERNAME with your macOS username.

Performance tips

  • Allocate enough RAM: 8 GB minimum for the VM. If running Ollama locally for AI analysis, allocate 12–16 GB.
  • Use SSD storage: The VM disk should be on your Mac's internal SSD, not an external drive.
  • Close unnecessary apps: Fusion and the VM will perform better when your Mac has free RAM.
  • Apple Silicon users: Use the native arm64.vmwarevm image for full performance. If you accidentally imported the x64 OVA, delete it and re-import the ARM build.
  • Disable visual effects: In VM Settings > Display, uncheck Accelerate 3D Graphics as CICADA IR is a server application and does not need GPU acceleration.

Fusion troubleshooting

OVA import fails

  • Verify the OVA file is not corrupted: shasum -a 256 cicada-ir-latest.ova
  • Ensure you have enough disk space for the import (requires ~2x the OVA size temporarily)
  • Try importing via OVFTool CLI as an alternative (see above)

VM has no network connectivity

  1. Verify the network adapter is connected (Settings > Network Adapter > Connect Network Adapter should be checked)
  2. Try switching between Bridged and NAT to isolate the issue
  3. Restart Fusion's networking:
    sudo /Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --stop
sudo /Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --start
  4. Inside the VM, restart networking: sudo netplan apply

VM performance is very slow

  • Check Activity Monitor on your Mac — if RAM pressure is high, close other applications or reduce VM RAM
  • Ensure the VM files are on your internal SSD, not an external or network drive
  • On Apple Silicon, make sure you are using the native arm64 image, not the x64 OVA

VM cannot connect to Ollama running on your Mac

If Ollama works from your Mac's browser (http://localhost:11434) but the CICADA IR VM gets "connection refused", your macOS firewall is likely blocking the incoming connection from the VM.

Why this happens:

  • Browsing from your Mac works — 127.0.0.1 and your Mac's IP both originate locally, so the firewall doesn't block them
  • The VM's traffic arrives as an incoming network connection, which the macOS firewall drops when set to block mode

Fix: Allow Ollama through the macOS firewall. Go to System Settings → Network → Firewall → Options and set Ollama to "Allow incoming connections". Or run:

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /Applications/Ollama.app/Contents/Resources/ollama

This switches Ollama from "Block" to "Allow incoming connections" without disabling the entire firewall.

"Cannot find a valid peer process to connect to"

This usually means the Fusion background services crashed. Fix:

# Force quit all VMware processes
killall -9 vmware-vmx vmware-usbarbitrator 2>/dev/null

# Restart Fusion
open -a "VMware Fusion"

Next steps