VirtualBox Installation Guide

Requirements

Enable Hardware Virtualization

VirtualBox requires hardware virtualization (VT-x on Intel, AMD-V on AMD). This is usually enabled by default but may need to be turned on in your BIOS/UEFI settings.

To check on Windows: Open Task Manager > Performance tab > look for "Virtualization: Enabled".

Step 1: Download VirtualBox

1. Go to: https://www.virtualbox.org/wiki/Downloads
2. Download the version for your operating system:
   • Windows: "Windows hosts"
   • macOS Intel: "macOS / Intel hosts"
   • macOS Apple Silicon: "macOS / ARM hosts" (M1/M2/M3/M4)
3. Run the installer with default settings
4. Restart your computer if prompted

Step 2: Download Ubuntu ISO

1. Go to: https://ubuntu.com/download/server
2. Download Ubuntu Server 24.04 LTS
3. Save the ISO file (approximately 2.5 GB)

Step 3: Create the Virtual Machine

1. Open VirtualBox and click New
2. Configure the basics:
   • Name: codehero
   • Folder: Leave default (or choose a location with enough space)
   • ISO Image: Click "Browse" and select the downloaded Ubuntu ISO
   • Check "Skip Unattended Installation"
3. Click Next
4. Hardware settings:
   • Base Memory: 4096 MB (or more if available)
   • Processors: 2 (or more)
5. Click Next
6. Virtual Hard Disk:
   • Select "Create a Virtual Hard Disk Now"
   • Size: 40 GB
7. Click Next then Finish

Step 4: Configure Network (Bridged)

By default, VirtualBox uses NAT networking, which makes the VM harder to access from your browser. Switch to Bridged mode so the VM gets its own IP on your local network.

1. Select the VM in the VirtualBox Manager
2. Click Settings
3. Go to Network > Adapter 1
4. Change "Attached to" from NAT to Bridged Adapter
5. In the "Name" dropdown, select your active network adapter:
   • For Wi-Fi: select your wireless adapter
   • For Ethernet: select your wired adapter
6. Click OK

Alternative: NAT with Port Forwarding

If bridged mode does not work (e.g., corporate networks), you can use NAT with port forwarding:

1. Keep "Attached to" as NAT
2. Click Advanced > Port Forwarding
3. Add these rules:

Access the dashboard at https://localhost:9453

Step 5: Install Ubuntu

1. Select the VM and click Start
2. The VM boots from the Ubuntu ISO

Ubuntu Installation Steps

1. Select Try or Install Ubuntu Server and press Enter
2. Language: Select your language
3. Keyboard: Select your keyboard layout
4. Type of Install: Select "Ubuntu Server"
5. Network: Ubuntu auto-detects the network. Note the IP if shown.
6. Proxy: Leave empty
7. Mirror: Leave default
8. Storage: Select "Use an entire disk" > select the virtual disk > Done > Done > Continue
9. Profile Setup:
   • Your name: Claude Admin
   • Server name: codehero-server
   • Username: claude
   • Password: Choose a password (remember it)
10. Ubuntu Pro: Select "Skip for now"
11. SSH: Check "Install OpenSSH server"
12. Featured Snaps: Skip, select Done
13. Wait for installation (5-10 minutes)
14. Select Reboot Now when prompted
15. Press Enter when asked to remove installation medium

First Login

Wait for the login prompt, then enter:

• Username: claude
• Password: the password you chose

Step 6: Install CodeHero

Run these commands inside the VM. First, copy the ZIP file provided with your CodeHero PRO license into the VM, then:

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.

Find Your VM IP Address

hostname -I

Write down the IP address (e.g., 192.168.1.105).

Step 7: Access the Dashboard

On your host machine (not inside the VM), open a browser and go to:

https://YOUR_VM_IP:9453

Default Login

• Username: admin
• Password: admin123

Change Default Passwords

Inside the VM:

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

Browser Security Warning

Daily Usage

Start the VM

GUI: Select the VM in VirtualBox Manager and click Start.

Headless (no window): Right-click the VM > Start > Headless Start. The VM runs in the background.

Command line:

# Normal start
VBoxManage startvm "codehero"

# Headless start (recommended for daily use)
VBoxManage startvm "codehero" --type headless

Stop the VM

GUI: Machine menu > ACPI Shutdown (graceful) or Power Off (force).

Command line:

# Graceful shutdown
VBoxManage controlvm "codehero" acpipowerbutton

# Force power off
VBoxManage controlvm "codehero" poweroff

Save VM State (Pause)

VBoxManage controlvm "codehero" savestate

This saves the VM state to disk and stops it. Next start resumes from where you left off.

Delete the VM

GUI: Right-click the VM > Remove > "Delete all files"

Command line:

VBoxManage unregistervm "codehero" --delete

SSH into the VM

Instead of using the VirtualBox console, you can SSH from your host:

ssh claude@YOUR_VM_IP

Troubleshooting

VM Won't Start: "VT-x is disabled"

Enable hardware virtualization in your BIOS/UEFI:

1. Restart your computer
2. Enter BIOS (usually F2, F12, Del, or Esc during boot)
3. Find Virtualization Technology (VT-x or AMD-V)
4. Enable it
5. Save and restart

No Network in the VM

1. Check that the network adapter is set to Bridged
2. Verify the correct host adapter is selected
3. Inside the VM, restart networking:

   sudo systemctl restart systemd-networkd

Cannot Access Dashboard from Browser

1. Verify the VM IP: hostname -I (inside VM)
2. Ensure you are using https:// not http://
3. Check that services are running:

   sudo systemctl status codehero-web

4. If using NAT, verify port forwarding rules are correct

VM Performance Is Slow

1. Increase RAM: Settings > System > Base Memory
2. Increase CPUs: Settings > System > Processor
3. Enable VT-x/AMD-V: Settings > System > Acceleration
4. Use a fixed-size disk instead of dynamically allocated
5. Install VirtualBox Guest Additions for better performance:

   sudo apt install -y virtualbox-guest-utils

Screen Resolution Too Small

Install Guest Additions:

sudo apt install -y virtualbox-guest-utils virtualbox-guest-x11
sudo reboot

Ubuntu Boot Hangs

• Ensure you selected "Skip Unattended Installation" when creating the VM
• Try disabling EFI: Settings > System > uncheck "Enable EFI"
• Verify the ISO downloaded correctly (check file size)