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 (see the next section to pick the right one for your Mac)

Which image do I need?

CICADA IR ships two images for Fusion. Pick the one that matches your Mac's processor:

Mac processorDownloadFormat
Apple Silicon (M1/M2/M3/M4)cicada-ir-<version>-arm64.tar.gzNative ARM bundle — extract, then open
Intelcicada-ir-<version>-x64.ovaStandard OVA — import via Fusion

Do not use the x64 OVA on Apple Silicon. It will run under binary translation and be significantly slower. The ARM build is fully native.

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)

Apple Silicon: extract and open

The Apple Silicon build ships as a .tar.gz containing a ready-to-run .vmwarevm bundle. No import step is needed.

  1. Download the cicada-ir-<version>-arm64.tar.gz file from your download link.
  2. Extract the archive. Double-click it in Finder, or run:
    cd ~/Downloads
tar -xzf cicada-ir-<version>-arm64.tar.gz
    This produces a cicada-ir-<version>.vmwarevm bundle.
  3. Move it to your Virtual Machines folder (optional but recommended):
    mv cicada-ir-<version>.vmwarevm ~/Virtual\ Machines/
  4. Open it — double-click the .vmwarevm bundle. Fusion launches, adds it to your library, and prompts you to power it on.
  5. If Fusion asks whether the VM was moved or copied, select I Copied It.

That's it. Skip ahead to Configure networking.

Intel: import the OVA

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 CICADA IR VM. Ollama runs on the Mac host (not inside the VM), so leave headroom on the Mac itself if you want local AI — 16 GB total system RAM is a practical minimum.
  • 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

Extraction or import fails

  • Apple Silicon (tar.gz): Verify the archive is not truncated with shasum -a 256 cicada-ir-<version>-arm64.tar.gz and compare against the hash on the download page. Ensure you have ~3× the archive size in free disk space for extraction.
  • Intel (OVA): Verify the OVA with shasum -a 256 cicada-ir-<version>-x64.ova. Ensure you have ~2× the OVA size in free disk space. Try 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. Restart the VM from Fusion (Virtual Machine > Restart) to force a fresh network handshake

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