QEMU Installation Guide

Requirements

QEMU supports hardware acceleration on all platforms:

• Linux: KVM (kernel-based, fastest)
• macOS: HVF (Hypervisor.framework)
• Windows: WHPX (Windows Hypervisor Platform) or TCG (slower, software emulation)

Step 1: Install QEMU

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install -y qemu-system-x86 qemu-utils qemu-system-arm

For KVM acceleration (highly recommended):

sudo apt install -y qemu-kvm libvirt-daemon-system
sudo usermod -aG kvm $USER
# Log out and back in for group change to take effect

Verify KVM is available:

kvm-ok

macOS (Homebrew)

brew install qemu

HVF (Hypervisor.framework) acceleration is available automatically on macOS.

Windows

1. Download QEMU for Windows from: https://www.qemu.org/download/#windows
2. Run the installer
3. Add QEMU to your PATH: The installer usually adds C:\Program Files\qemu to PATH. If not, add it manually.
4. Verify installation:

   qemu-system-x86_64 --version

For WHPX acceleration on Windows, enable "Windows Hypervisor Platform" in Windows Features:

Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform

Step 2: Download Ubuntu ISO

For x86_64 (Intel/AMD systems)

1. Go to: https://ubuntu.com/download/server
2. Download Ubuntu Server 24.04 LTS

For aarch64 (Apple Silicon Macs or ARM systems)

1. Go to: https://ubuntu.com/download/server/arm
2. Download Ubuntu Server 24.04 LTS for ARM

Also download the UEFI firmware for ARM:

# macOS
brew install qemu  # Includes edk2-aarch64-code.fd

# Linux
sudo apt install -y qemu-efi-aarch64

Step 3: Create the Virtual Machine

Create a Virtual Disk

qemu-img create -f qcow2 codehero.qcow2 40G

This creates a 40 GB dynamically-allocated disk image (it only uses space as data is written).

x86_64 VM (Intel/AMD)

Linux (with KVM acceleration)

qemu-system-x86_64 \
  -name codehero \
  -machine type=q35,accel=kvm \
  -cpu host \
  -smp 2 \
  -m 4096 \
  -drive file=codehero.qcow2,format=qcow2 \
  -cdrom ubuntu-24.04-live-server-amd64.iso \
  -boot d \
  -nic user,hostfwd=tcp::2222-:22,hostfwd=tcp::9453-:9453,hostfwd=tcp::9867-:9867 \
  -nographic

macOS (with HVF acceleration)

qemu-system-x86_64 \
  -name codehero \
  -machine type=q35,accel=hvf \
  -cpu host \
  -smp 2 \
  -m 4096 \
  -drive file=codehero.qcow2,format=qcow2 \
  -cdrom ubuntu-24.04-live-server-amd64.iso \
  -boot d \
  -nic user,hostfwd=tcp::2222-:22,hostfwd=tcp::9453-:9453,hostfwd=tcp::9867-:9867 \
  -nographic

Windows (with WHPX acceleration)

qemu-system-x86_64 ^
  -name codehero ^
  -machine type=q35,accel=whpx ^
  -cpu qemu64 ^
  -smp 2 ^
  -m 4096 ^
  -drive file=codehero.qcow2,format=qcow2 ^
  -cdrom ubuntu-24.04-live-server-amd64.iso ^
  -boot d ^
  -nic user,hostfwd=tcp::2222-:22,hostfwd=tcp::9453-:9453,hostfwd=tcp::9867-:9867 ^
  -nographic

aarch64 VM (Apple Silicon / ARM)

This is the correct approach for M1/M2/M3/M4 Macs.

macOS Apple Silicon (with HVF acceleration)

qemu-system-aarch64 \
  -name codehero \
  -machine virt,accel=hvf \
  -cpu host \
  -smp 2 \
  -m 4096 \
  -bios /opt/homebrew/share/qemu/edk2-aarch64-code.fd \
  -drive file=codehero.qcow2,format=qcow2,if=virtio \
  -cdrom ubuntu-24.04-live-server-arm64.iso \
  -boot d \
  -device virtio-net-pci,netdev=net0 \
  -netdev user,id=net0,hostfwd=tcp::2222-:22,hostfwd=tcp::9453-:9453,hostfwd=tcp::9867-:9867 \
  -nographic

Linux ARM (with KVM acceleration)

qemu-system-aarch64 \
  -name codehero \
  -machine virt,accel=kvm \
  -cpu host \
  -smp 2 \
  -m 4096 \
  -bios /usr/share/qemu-efi-aarch64/QEMU_EFI.fd \
  -drive file=codehero.qcow2,format=qcow2,if=virtio \
  -cdrom ubuntu-24.04-live-server-arm64.iso \
  -boot d \
  -device virtio-net-pci,netdev=net0 \
  -netdev user,id=net0,hostfwd=tcp::2222-:22,hostfwd=tcp::9453-:9453,hostfwd=tcp::9867-:9867 \
  -nographic

Step 4: Network Configuration

The commands above use user-mode networking with port forwarding. This is the simplest setup and does not require root/admin privileges.

Port Forwarding (Default)

The -nic user,hostfwd=... flag forwards these ports from your host to the VM:

Access the dashboard at https://localhost:9453.

Bridge Networking (Advanced)

For a separate IP on your network (Linux only with KVM):

# Create a bridge (one-time setup)
sudo ip link add br0 type bridge
sudo ip link set br0 up
sudo ip link set eth0 master br0  # Replace eth0 with your interface
sudo dhclient br0

# Start VM with bridge networking
qemu-system-x86_64 \
  -name codehero \
  -machine type=q35,accel=kvm \
  -cpu host \
  -smp 2 \
  -m 4096 \
  -drive file=codehero.qcow2,format=qcow2 \
  -nic bridge,br=br0 \
  -nographic

Step 5: Install Ubuntu

When the VM boots (using -nographic, the installer runs in your terminal):

1. Select Try or Install Ubuntu Server
2. Follow the installation wizard:
   • Language: Select your language
   • Keyboard: Select your layout
   • Type of Install: Ubuntu Server
   • Network: Auto-detected
   • Proxy: Leave empty
   • Mirror: Leave default
   • Storage: Use entire disk
   • Profile Setup:
     • Your name: Claude Admin
     • Server name: codehero-server
     • Username: claude
     • Password: Choose a password
   • Ubuntu Pro: Skip
   • SSH: Check "Install OpenSSH server"
   • Featured Snaps: Skip
3. Wait for installation to finish
4. Select Reboot Now
5. Close the QEMU window (or press Ctrl+A then X in nographic mode) when it hangs on removing installation medium

Boot Without the ISO (After Installation)

After Ubuntu is installed, start the VM without the -cdrom and -boot d flags:

x86_64

qemu-system-x86_64 \
  -name codehero \
  -machine type=q35,accel=kvm \
  -cpu host \
  -smp 2 \
  -m 4096 \
  -drive file=codehero.qcow2,format=qcow2 \
  -nic user,hostfwd=tcp::2222-:22,hostfwd=tcp::9453-:9453,hostfwd=tcp::9867-:9867 \
  -nographic

aarch64 (Apple Silicon)

qemu-system-aarch64 \
  -name codehero \
  -machine virt,accel=hvf \
  -cpu host \
  -smp 2 \
  -m 4096 \
  -bios /opt/homebrew/share/qemu/edk2-aarch64-code.fd \
  -drive file=codehero.qcow2,format=qcow2,if=virtio \
  -device virtio-net-pci,netdev=net0 \
  -netdev user,id=net0,hostfwd=tcp::2222-:22,hostfwd=tcp::9453-:9453,hostfwd=tcp::9867-:9867 \
  -nographic

Step 6: Install CodeHero

SSH into the VM (or use the console):

ssh -p 2222 claude@localhost

Then copy the ZIP file provided with your CodeHero PRO license into the VM and run:

sudo apt update
sudo apt install -y unzip wget net-tools
sudo su
cd /root
unzip codehero-pro-release-4.6.3.zip
cd codehero
chmod +x setup.sh
./setup.sh

Wait 10-15 minutes for installation to complete.

Step 7: Access the Dashboard

On your host machine, open a browser and go to:

https://localhost:9453

(If using bridge networking, use the VM's IP instead of localhost.)

Default Login

• Username: admin
• Password: admin123

Change Default Passwords

Inside the VM:

sudo /opt/codehero/scripts/change-passwords.sh

Browser Security Warning

Daily Usage

Create a Start Script

To avoid typing long commands, create a shell script:

start-codehero.sh (Linux/macOS)

#!/bin/bash
qemu-system-x86_64 \
  -name codehero \
  -machine type=q35,accel=kvm \
  -cpu host \
  -smp 2 \
  -m 4096 \
  -drive file=$HOME/codehero.qcow2,format=qcow2 \
  -nic user,hostfwd=tcp::2222-:22,hostfwd=tcp::9453-:9453,hostfwd=tcp::9867-:9867 \
  -nographic &

echo "CodeHero VM started. Dashboard: https://localhost:9453"
echo "SSH: ssh -p 2222 claude@localhost"

chmod +x start-codehero.sh

SSH into the VM

ssh -p 2222 claude@localhost

Stop the VM

From inside the VM:

sudo shutdown now

From the host (if using the QEMU monitor):

• Press Ctrl+A then C to enter the QEMU monitor
• Type quit and press Enter

QEMU Monitor Commands

Press Ctrl+A then C to toggle the QEMU monitor:

Press Ctrl+A then C again to return to the VM console.

Delete the VM

Simply delete the disk image:

rm codehero.qcow2

Troubleshooting

"Could not access KVM kernel module"

KVM is not available. Check:

# Verify KVM support
lsmod | grep kvm

# Install KVM
sudo apt install -y qemu-kvm
sudo usermod -aG kvm $USER
# Log out and back in

If running inside another VM (nested virtualization), KVM may not be available. Use accel=tcg instead.

"HVF is not available" on macOS

1. Ensure you are on macOS 10.15 or later
2. Check that no other hypervisor is locking HVF
3. Fall back to accel=tcg (slower)

VM Hangs During Boot

1. Ensure you are using the correct ISO for your architecture (x86_64 vs aarch64)
2. For aarch64, verify the UEFI firmware path is correct
3. Try adding -serial mon:stdio instead of -nographic for better console output

No Network Inside the VM

1. Verify port forwarding is correctly specified in the QEMU command
2. Inside the VM:

   ip addr show
   sudo dhclient

Cannot Connect to Dashboard

1. Verify port forwarding: hostfwd=tcp::9453-:9453
2. Check the VM is fully booted and services are running:

   ssh -p 2222 claude@localhost
   sudo systemctl status codehero-web

3. Ensure no other process is using port 9453 on your host

Performance Is Slow

1. Ensure hardware acceleration is enabled (accel=kvm, accel=hvf, or accel=whpx)
2. Use accel=tcg only as a last resort (10-50x slower)
3. Increase memory: -m 8192
4. Increase CPUs: -smp 4
5. Use virtio drivers for disk and network (already included in the aarch64 examples)

QEMU Window Does Not Appear

If using -nographic, there is no graphical window. The VM console appears in your terminal. If you want a graphical window, remove -nographic from the command.