Installation

System requirements

Install from .dmg

The .dmg is the recommended path for everyday use. It's signed with a Developer ID certificate and notarized by Apple, which means Gatekeeper trusts it on first launch.

1. Download the latest release from the GitHub releases page.
2. Verify the download (the SHA-256 is published next to the asset on the releases page):

   shasum -a 256 SecVF-x.y.z.dmg
   # compare against the SHA-256 column on the release page

3. Mount the .dmg by double-clicking. Drag SecVF.app into Applications.
4. Eject the disk image, then launch SecVF from Applications or Spotlight.

Build from source

Use this path if you want the latest commit, want to modify SecVF, or are setting up a contributor environment.

Clone

git clone https://github.com/DaxxSec/SecVF.git
cd SecVF

Build with Xcode (GUI)

1. open SecVF.xcodeproj
2. Select the SecVF scheme and the My Mac (Designed for iPad off) destination.
3. Press ⌘R to build & run.

Build from the command line

# Debug
xcodebuild -scheme SecVF -configuration Debug \
           -destination 'platform=macOS,arch=arm64' build

# Release
xcodebuild -scheme SecVF -configuration Release \
           -destination 'platform=macOS,arch=arm64' build

The product appears at ~/Library/Developer/Xcode/DerivedData/SecVF-*/Build/Products/<config>/SecVF.app.

Code signing for personal use

To run a custom build outside Xcode you need a signed binary — the Virtualization framework refuses to load unsigned guest configurations. Easiest path is your free Apple ID team:

# Pick the team in the Xcode project settings:
# SecVF target → Signing & Capabilities → Team → <your Apple ID>
# Bundle ID must be unique per team — change it from the default if you hit
# "this bundle id is already in use".

Optional dependencies

tshark (packet capture)

Without tshark, the live packet panel still receives switch frames, but the deep-decode and PCAP export paths are disabled.

brew install wireshark            # CLI + GUI
# or, headless-only:
brew install wireshark --no-quarantine --formula  # CLI only

SecVF discovers tshark via $PATH. After install, restart the app — it caches the binary path on launch.

just (CLI quality-of-life)

The repo's justfile wraps common dev commands. Optional, only if you're building from source frequently.

brew install just
just                              # see available recipes

First run & permissions

On first launch SecVF prompts macOS for two permissions. Grant both.

SecVF does not ask for Full Disk Access, Accessibility, Screen Recording, or Camera. If a future build requests one of these, read the change log first — there should be a clear reason.

Data directory layout

Everything SecVF persists lives under ~/.avf/ in your home directory:

~/.avf/
├── Linux/<VMName>.bundle/      # Linux guest VMs
│   ├── Disk.img                # Disk image (sparse)
│   ├── NVRAM                   # Virtual NVRAM
│   ├── MachineIdentifier       # Stable VM ID
│   └── metadata.json           # CPU/RAM/network mode
├── MacOS/<VMName>.bundle/      # macOS guest VMs (same shape + .ipsw)
├── AISandbox/                  # AI sandbox base images + sessions
├── ISOCache/                   # SHA-256-verified ISO downloads
└── logs/
    ├── security-YYYY-MM-DD.log # Security event log (rotated daily)
    └── error-audit.log         # Typed-error audit trail

Verify the install

Quick sanity checks after launch:

1. Menu bar shows "SecVF" — app launched and is the front process.
2. VM Library window opens — the empty state shows the "+ New VM" button.
3. Settings → About shows your version and build commit hash.
4. Optional: tshark detected — open Packet Analysis (⌘⇧P); if tshark is installed and on $PATH, the "Start capture" button is enabled.

If anything looks off, the audit log usually has the answer:

tail -f ~/.avf/logs/error-audit.log

Uninstall

Three steps to leave no trace:

# 1. Quit SecVF
osascript -e 'quit app "SecVF"'

# 2. Remove the application
rm -rf /Applications/SecVF.app

# 3. Remove the data directory (this includes all VM bundles and logs)
rm -rf ~/.avf