UTM Installation Guide

Requirements

Why UTM?

Step 1: Download UTM

From the Website (Free)

1. Go to: https://mac.getutm.app/
2. Click Download
3. Open the downloaded DMG file
4. Drag UTM to your Applications folder
5. Launch UTM from Applications

From the App Store (Paid)

1. Open the App Store
2. Search for "UTM"
3. Purchase and install (supports the developer)

Both versions are identical in functionality.

Step 2: Download Ubuntu ARM ISO

For Apple Silicon Macs, you need the ARM version of Ubuntu.

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

Step 3: Create the Virtual Machine

1. Open UTM
2. Click Create a New Virtual Machine
3. Select Virtualize (uses Apple's Hypervisor.framework for native speed)
4. Select Linux
5. Under "Boot ISO Image", click Browse and select the Ubuntu ARM ISO
6. Click Continue
7. Hardware settings:
   • Memory: 4096 MB
   • CPU Cores: 2 (or more)
   • Leave "Enable hardware OpenGL acceleration" unchecked (not needed for a server)
8. Click Continue
9. Storage: Size: 40 GB
10. Click Continue
11. Shared Directory: Skip (click Continue)
12. Summary: Name: codehero — Review settings
13. Click Save

Step 4: Network Configuration

By default, UTM uses shared networking (similar to NAT) which works fine with port forwarding. For easier access, switch to bridged mode.

Option A: Bridged Networking (Recommended)

Bridged mode gives the VM its own IP on your local network.

1. In UTM, right-click the codehero VM > Edit
2. Go to Network
3. Change "Network Mode" to Bridged (Advanced)
4. Select your network interface (usually en0 for Wi-Fi)
5. Click Save

With bridged networking, access the dashboard using the VM's own IP address.

Option B: Shared Networking with Port Forwarding

Keep the default shared networking and add port forwarding:

1. Right-click the VM > Edit
2. Go to Network
3. Ensure "Network Mode" is Shared Network
4. Under "Port Forward", add these rules:

With shared networking, access the dashboard at https://localhost:9453.

Step 5: Install Ubuntu

1. Select the codehero VM in UTM
2. Click the Play button to start the VM
3. Select Try or Install Ubuntu Server and press Enter

Ubuntu Installation Steps

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

Remove the ISO After Installation

After the VM reboots:

1. If the VM boots back into the installer, stop the VM (click the Stop button)
2. Right-click the VM > Edit
3. Find the IDE Drive that contains the ISO
4. Click Clear to remove the ISO
5. Click Save
6. Start the VM again

First Login

At the login prompt:

• 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 (e.g., 192.168.1.115).

Step 7: Access the Dashboard

On your Mac, open a browser and go to:

• Bridged networking: https://YOUR_VM_IP:9453
• Shared networking: https://localhost: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

1. Open UTM
2. Select the codehero VM
3. Click the Play button

The VM starts in a few seconds and services start automatically with Ubuntu.

Stop the VM

1. Click the Stop button in UTM, or
2. Use the VM menu button > Request Power Down (graceful shutdown)

From inside the VM:

sudo shutdown now

Save VM State (Snapshot)

Right-click the VM > Clone (creates a full copy). Or from inside the VM, use UTM's snapshot features if available.

Delete the VM

1. Stop the VM if running
2. Right-click the VM > Delete
3. Confirm deletion

SSH into the VM

From your Mac terminal:

# Bridged networking
ssh claude@YOUR_VM_IP

# Shared networking with port forwarding
ssh -p 2222 claude@localhost

Check Services

SSH into the VM and run:

sudo systemctl status codehero-web codehero-daemon

Troubleshooting

VM Won't Start: "Failed to start"

1. Ensure you selected Virtualize (not "Emulate") for Apple Silicon
2. Check that the ISO/disk is not corrupted
3. Try creating a new VM from scratch

No Network Connection

1. Check UTM network settings (bridged vs shared)
2. For bridged mode, verify the correct interface is selected (en0 for Wi-Fi, en1 for Ethernet on some Macs)
3. Inside the VM:

   ip addr show
   sudo dhclient enp0s1

Cannot Access Dashboard

1. Bridged mode: Verify VM IP with hostname -I inside the VM
2. Shared mode: Verify port forwarding rules are configured
3. Check services are running:

   sudo systemctl status codehero-web

VM Runs Slowly

1. Increase memory: Edit VM > System > Memory > 8192 MB
2. Increase CPUs: Edit VM > System > CPU Cores > 4
3. Ensure you chose Virtualize (not "Emulate") — emulation is much slower
4. Close other resource-heavy apps on your Mac

Cannot Download Files Inside the VM

DNS may not be configured. Fix:

echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Screen Too Small / Cannot See Full Terminal

1. Resize the UTM window
2. Or SSH into the VM from your Mac terminal for a better experience:

   ssh claude@YOUR_VM_IP

UTM Crashes on Launch

1. Ensure you have the latest version of UTM
2. Check macOS compatibility (UTM requires macOS 11+)
3. Try downloading from the website instead of the App Store (or vice versa)

"Virtualize" Option Not Available

This happens on Intel Macs when trying to run ARM ISOs. Either:

• Use the x86_64 Ubuntu ISO with "Emulate" mode (slower)
• Use VirtualBox instead (better performance for Intel Macs)