Get started · Your first VM

Your first VM

From empty library to a booted Ubuntu desktop in under ten minutes. We'll start with NAT mode — the simplest network setup — then graduate to virtual-switch and router-VM modes on later pages.

On this page

Open the VM Library

Launch SecVF. The VM Library window opens automatically — it's the home base for everything. Three panels:

  • VM table (center) — every VM, its status, network mode, RAM.
  • Active VMs sidebar (left) — running guests, click to switch.
  • Packet log panel (bottom) — live frames once you start capture.

The empty state shows a + New VM button. Click it (or press ⌘N).

Create a new Linux VM

The new-VM sheet asks for the basics. For a first run, accept the defaults and tweak:

FieldSuggested first-run valueNotes
Nameubuntu-testLowercase, hyphens. Becomes the bundle directory name.
OS familyLinuxmacOS guest is a separate flow (Apple Silicon only) — see Managing VMs.
DistroUbuntu 24.04 LTSPulled from distros.json; eight options ship by default. Versions are dynamically discovered from official mirrors.
CPU cores2Don't allocate more than half the host's physical cores for a guest you might run in parallel with others.
RAM4096 MB2 GB is enough for headless Linux; bump to 4–8 GB for a desktop install.
Disk20 GBSparse — actual size on disk grows with use, capped here.
Network modeNATEasiest to start. Internet access via the host. We'll change this later.

Click Create. SecVF writes the bundle to ~/.avf/Linux/ubuntu-test.bundle/ and queues an ISO download if the distro isn't already cached.

How the ISO cache works

SecVF doesn't redownload ISOs. Once a distro version is pulled, it's stored under ~/.avf/ISOCache/ and reused for every new VM.

  • Source: the official mirror listed in Resources/distros.json. URLs are pinned to specific hostnames; downloads from anywhere else are refused.
  • Verification: the ISO's SHA-256 checksum is fetched from the same mirror's SHA256SUMS file (or equivalent) and compared against the download. A mismatch deletes the file and surfaces a CRITICAL security event.
  • Audit: open Monitoring → ISO Cache Audit (⌘⇧4) to see every download, its checksum, source URL, and verification result.
If the download is slow, it's the upstream mirror — SecVF doesn't proxy or cache between users. You can pre-seed the cache by dropping a verified ISO into ~/.avf/ISOCache/ with the exact filename SecVF expects (the audit log shows what name it tried).

First boot & install

  1. Select your VM in the table. Click Start (or ⌘S).
  2. SecVF opens a dedicated window for the guest. The Apple Virtualization framework boots EFI, then the ISO's bootloader.
  3. Run the distro installer the same way you would on bare metal.
    • Use the entire disk — it's a 20 GB virtual disk, not your host.
    • Create a user with a strong password — the VM has network access via NAT.
    • Install the SSH server if the distro asks; it's useful for headless workflows later.
  4. When the installer prompts to reboot, shut down the VM instead (in the guest's menu, or ⌘. in SecVF). After it stops, eject the ISO from the VM's settings — otherwise it'll boot back into the installer on next start.
  5. Click Start again. You're now booting the installed system.
Don't use a malware-test ISO on a NAT-mode VM. NAT gives the guest internet access through your host's network. For analysis workflows, switch the VM to virtual-switch or router-VM mode before introducing hostile workloads.

Post-install: tools to install in the guest

For a general-purpose Linux sandbox you'll want a baseline of tools. Here's what to grab on first login (Ubuntu/Debian-flavored):

sudo apt update
sudo apt install -y \
    curl wget git build-essential \
    tcpdump tshark net-tools dnsutils \
    htop tmux vim
# Optional GUI tools for desktop installs:
sudo apt install -y wireshark gnome-tweaks

These won't be on the host's $PATH — they live inside the guest. Each VM has its own world.

Stopping & pausing

ActionShortcutWhat it does
Graceful shutdown—Use the guest OS's shutdown — sends ACPI signal, kernel does an orderly stop.
Force stop⌘.Pulls the plug. May corrupt unflushed writes — only when the guest is stuck.
Pause—Suspend the VM — RAM stays allocated, no CPU cycles. Resume puts it back exactly where it was.
Close the window⌘WCloses the display window but keeps the VM running. Reopen from the VM Library.

What's next

Now that you have one VM running, you can branch in any of three directions:

  • Network modes — switch off NAT to virtual-switch or router-VM mode, which is what you want for malware analysis.
  • Packet analysis — start a live capture, write display filters, export PCAP.
  • Managing VMs — multi-window sessions, snapshots, the macOS guest install path.
Previous ← Installation