AiFw

Install AiFw

AiFw runs on FreeBSD 15+ and anything that can boot a FreeBSD ISO — physical hardware, KVM, VMware, Proxmox, or any cloud VM.

Grab the latest ISO from the releases page:

# ISO (for CD/DVD or VM boot)
aifw-X.Y.Z-amd64.iso.xz

# USB image (for a USB installer stick)
aifw-X.Y.Z-amd64.img.xz

Uncompress first:

xz -d aifw-*-amd64.iso.xz

Boot from ISO

  1. Attach the ISO to your VM or burn it to a USB/DVD
  2. Boot — you’ll land in the AiFw console menu (OPNsense-style)
  3. Select option 14 to install to disk (ZFS or UFS)
  4. After install and reboot, the first-boot wizard runs automatically

Write USB image

# Linux/macOS
sudo dd if=aifw-X.Y.Z-amd64.img of=/dev/sdX bs=1M status=progress

# FreeBSD
sudo dd if=aifw-X.Y.Z-amd64.img of=/dev/daX bs=1M

First-boot setup wizard

The wizard walks you through everything:

  1. Root password and SSH access
  2. Hostname
  3. System tuning (auto-detected based on CPU + RAM)
  4. Network interfaces (WAN / LAN detection)
  5. Admin user + 2FA
  6. DNS servers
  7. Firewall policy (Standard / Strict / Permissive)

Once done, reach the web UI at:

https://<lan-ip>:8080

Minimum requirements

Resource Minimum Recommended
CPU 1 core (amd64) 2+ cores, AES-NI
RAM 1 GB 4 GB+ (more for IDS)
Disk 4 GB 16 GB SSD
NIC 1 (single-arm) 2+ (WAN + LAN)

The memory cache sizing (IDS alert buffer, dashboard history) scales automatically with detected RAM.

Update from the CLI

If the web UI breaks, the console has built-in update commands:

aifw update check      # see if an update is available
aifw update install    # download, verify, install, restart
aifw update rollback   # revert to the previous version

Platform support

Platform Status
Bare metal (amd64) Supported
KVM / Proxmox Supported
VMware ESXi Supported
bhyve Supported
AWS / DigitalOcean FreeBSD images Untested, should work
arm64 (Raspberry Pi, Ampere) Planned

Troubleshooting

Can’t reach the web UI? Console → option 7 (Reset root password) → check that aifw_api is running:

service aifw_api status

Locked yourself out with a rule change? Every apply triggers commit-confirm. If you don’t click Confirm within 2 minutes, the config auto-reverts.

Service died silently? All services run under daemon(8) with -R 5 auto-restart. Check /var/log/aifw/*.log for crash details.

Next steps