Installation

Installation

Bull runs on Linux, either natively or inside WSL2. It needs Vagrant, a hypervisor, and a handful of CLI tools. The bundled install.sh can set up everything unattended, or you can install the pieces yourself.

1. Get the code

git clone https://github.com/WhiteMuush/Bull.git
cd Bull

2. Install host dependencies

Option A — unattended installer (recommended)

install.sh detects your distribution and installs Vagrant plus a hypervisor without prompting.

sudo ./install.sh

Supported families:

Family	Package manager
Debian / Ubuntu / Kali / Parrot	apt
Fedora / RHEL / Rocky / AlmaLinux	dnf / yum
Arch / Manjaro	pacman
openSUSE Leap / Tumbleweed	zypper

Architectures: x86_64, arm64.

Flags:

sudo ./install.sh --provider libvirt      # force libvirt/KVM
sudo ./install.sh --provider virtualbox   # force VirtualBox
sudo ./install.sh --skip-provider         # install Vagrant only

Option B — manual

Install these yourself, then let Bull verify them:

• Vagrant 2.3+ — on Ubuntu 24.04+ it is no longer in apt; Bull adds the official HashiCorp repo automatically when needed.
• A hypervisor — libvirt + qemu-kvm + ovmf (preferred), or VirtualBox.
• jq, gpg, ssh, openssl — usually already present.
• sshpass — optional, only needed for some custom-user SSH flows.

3. Initialize Bull

sudo ./bull.sh init

init checks every dependency, sets up the libvirt storage pool and NAT network (libvirt provider), installs the vagrant-libvirt plugin if missing, and creates the inventory. Fix anything it reports before creating a VM.

After init you can call bull directly instead of ./bull.sh.

Providers

Bull auto-selects a provider:

• libvirt/KVM when /dev/kvm exists. This is the preferred path: the whole stack stays in Linux, no Windows tooling required. VM images live in /var/lib/libvirt/images/.
• VirtualBox otherwise. VM files live under ~/VirtualBox VMs/.

Force a provider for the whole session:

export BULL_PROVIDER=libvirt      # or virtualbox

WSL2

Bull detects WSL2 from /proc/version and adapts automatically:

• It exports VAGRANT_WSL_ENABLE_WINDOWS_ACCESS=1 (Vagrant refuses to run on WSL2 without it).

• With libvirt it keeps everything on the Linux side, pins VAGRANT_HOME to ~/.vagrant.d, and shims cmd.exe / powershell.exe so Vagrant's Windows checks pass without invoking real Windows binaries. This is the recommended WSL2 setup.

• With VirtualBox it stores VM files on the Windows filesystem (/mnt/c/...), because the Windows VirtualBox process cannot reach the WSL2 ext4 filesystem. Bull resolves your Windows home and sets BULL_HOME there. If it cannot, set it yourself:

  export BULL_HOME=/mnt/c/Users/<you>/.bull

To enable KVM inside WSL2, add nested virtualization to ~/.wslconfig on Windows:

[wsl2]
nestedVirtualization=true

Then run wsl --shutdown and reopen your distro.

Reclaiming disk space on WSL2

WSL2 stores its filesystem in a .vhdx that grows but never shrinks on its own. After destroying VMs the space is free inside WSL2, but Windows still sees the file at peak size. To reclaim it on the Windows side:

# 1. Shut down WSL2
wsl --shutdown

# 2. Compact the disk (PowerShell as Administrator, requires Hyper-V)
$vhdx = (Get-ChildItem "$env:LOCALAPPDATA\Packages\*\LocalState\ext4.vhdx" -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1).FullName
Optimize-VHD -Path $vhdx -Mode Full

Without Hyper-V, use diskpart instead:

diskpart
select vdisk file="C:\Users\<you>\AppData\Local\Packages\<distro>\LocalState\ext4.vhdx"
compact vdisk
exit

First run expectations

The first bull create takes 10–15 minutes. It downloads the Vagrant box (~2–4 GB for Kali, and a ~9 GB OVA for Parrot on first use) and installs hypervisor dependencies. Subsequent VMs from the same box are much faster.

Next: the Usage Guide.