Windows WSL2 Installation Guide

What is WSL2?

WSL2 (Windows Subsystem for Linux 2) runs a real Linux kernel directly on Windows without the overhead of a traditional virtual machine.

Requirements

Check Your Windows Version

Press Win + R, type winver, and press Enter. You need:

• Windows 10 version 2004 or higher (Build 19041+)
• Windows 11 (any version)

Verify Virtualization Is Enabled

Open Task Manager (Ctrl + Shift + Esc), go to the Performance tab, and check that Virtualization shows as "Enabled". If it is not enabled, you need to enable VT-x or AMD-V in your BIOS settings.

Method 1: One-Click Installer (Recommended)

This is the fastest way to get CodeHero running on Windows.

Step 1: Locate the CodeHero ZIP

Use the ZIP file provided with your CodeHero PRO license. If you have not downloaded it yet, log in to your CodeHero PRO account to obtain it.

Step 2: Extract the ZIP

Extract the ZIP file to any folder (e.g., C:\Users\YourName\Downloads\codehero).

Step 3: Run setup.bat

Navigate into the extracted codehero folder and find the multipass subfolder. Double-click setup.bat (or right-click and "Run as administrator").

The installer will:

1. Check if WSL is installed (installs it if needed)
2. Install Ubuntu 24.04 in WSL
3. Enable systemd for service management
4. Install CodeHero inside WSL
5. Start all services
6. Create desktop shortcuts for easy access
7. Open the dashboard in your default browser

Step 4: Restart if Prompted

If WSL was not previously installed, Windows will require a restart. After restarting, run setup.bat again to continue the installation.

Installation Time

Method 2: Manual Installation

If you prefer full control over each step, follow this manual process.

Step 1: Enable WSL

Open PowerShell as Administrator (right-click Start menu, select "Terminal (Admin)" or "Windows PowerShell (Admin)"):

wsl --install -d Ubuntu-24.04

Restart your computer when prompted.

Step 2: First Launch

After restart, open PowerShell and run:

wsl -d Ubuntu-24.04

On first launch, you will be asked to create a UNIX username and password. Create them and remember them.

Step 3: Enable Systemd

Systemd is required for CodeHero services. Inside the WSL terminal:

sudo su
echo -e '[boot]\nsystemd=true\n\n[user]\ndefault=root' > /etc/wsl.conf
exit
exit

Back in PowerShell, restart WSL to apply the change:

wsl --shutdown

Wait 5 seconds, then start WSL again:

wsl -d Ubuntu-24.04

Step 4: Install CodeHero

You should now be root inside WSL. Extract the ZIP file provided with your license and run the setup:

apt-get update
apt-get install -y unzip wget net-tools

cd /root
# Copy the CodeHero PRO ZIP to this directory, then:
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 5: Get Your IP Address

hostname -I

Note the IP address (e.g., 172.25.123.45). You will need it to access the dashboard.

Post-Install Setup

Access the Dashboard

Open your browser (on Windows, not inside WSL) and go to:

https://YOUR_WSL_IP:9453

Replace YOUR_WSL_IP with the IP from hostname -I (e.g., https://172.25.123.45:9453).

Default Login Credentials

• Username: admin
• Password: admin123

Change Default Passwords

Inside WSL:

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

Browser Security Warning

You will see a security warning due to the self-signed SSL certificate. This is normal.

Install Claude Code CLI

/opt/codehero/scripts/install-claude-code.sh

Access URLs

Daily Usage

Start WSL and Services

Services start automatically when WSL boots with systemd. Simply open WSL:

From PowerShell:

wsl -d Ubuntu-24.04

If services are not running, start them manually:

From PowerShell (without entering WSL):

wsl -d Ubuntu-24.04 --exec systemctl start mysql nginx php8.3-fpm codehero-web codehero-daemon

From inside WSL:

systemctl start mysql nginx php8.3-fpm codehero-web codehero-daemon

Check Service Status

systemctl status codehero-web codehero-daemon

Get Current IP Address

The WSL IP address may change after each restart. Always check before accessing the dashboard.

From PowerShell:

wsl -d Ubuntu-24.04 --exec hostname -I

From inside WSL:

hostname -I

Shutdown WSL

wsl --shutdown

This gracefully stops all WSL instances and frees up system resources.

List Installed Distros

wsl --list --verbose

Desktop Shortcuts

If you used the one-click installer (setup.bat), two shortcuts are created on your Desktop:

CodeHero (WSL).bat

Double-click to:

1. Start WSL and all services
2. Detect the current IP address
3. Open the dashboard in your default browser

This is the recommended way to launch CodeHero daily.

CodeHero Dashboard (WSL).url

A direct bookmark to the dashboard. Note that if the WSL IP changes after a restart, this link may point to an outdated address. Use the .bat shortcut instead for reliable access.

WSL Persistence

Does WSL Keep My Data?

Yes. WSL persists all data between restarts. Your projects, tickets, and configuration are stored inside the WSL filesystem and survive reboots.

What Happens When I Shut Down Windows?

WSL shuts down automatically. When you start WSL again, services will start automatically (if systemd is enabled).

Backup WSL

To export your entire WSL instance as a backup:

wsl --export Ubuntu-24.04 C:\Backups\codehero-wsl-backup.tar

To restore from a backup:

wsl --import Ubuntu-24.04-restored C:\WSL\Ubuntu-restored C:\Backups\codehero-wsl-backup.tar

File Access

Access WSL Files from Windows

In File Explorer, type in the address bar:

\\wsl$\Ubuntu-24.04

To go directly to the CodeHero installation:

\\wsl$\Ubuntu-24.04\opt\codehero

To access web project files:

\\wsl$\Ubuntu-24.04\var\www\projects

Access Windows Files from WSL

Your Windows drives are mounted under /mnt:

# Windows C: drive
cd /mnt/c

# Your Windows user folder
cd /mnt/c/Users/YourUsername

# Windows Desktop
cd /mnt/c/Users/YourUsername/Desktop

Troubleshooting

"System has not been booted with systemd"

Systemd is not enabled. Fix it:

# Inside WSL
sudo su
echo -e '[boot]\nsystemd=true' > /etc/wsl.conf
exit
exit

Then in PowerShell:

wsl --shutdown
wsl -d Ubuntu-24.04

Cannot Access Dashboard

1. Check services are running:

   systemctl status codehero-web

2. Get current IP:

   hostname -I

3. Start services if stopped:

   systemctl start mysql nginx php8.3-fpm codehero-web codehero-daemon

4. Windows Firewall: When prompted, allow the connection. Or manually add an inbound rule for port 9453 in Windows Defender Firewall.

WSL Will Not Start

# Check WSL status
wsl --status

# Update WSL to latest version
wsl --update

# Restart the WSL service
net stop LxssManager
net start LxssManager

"Virtual Machine Platform" Error

Enable required Windows features (PowerShell as Admin):

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Restart your computer after running these commands.

IP Address Changes After Restart

This is normal WSL behavior. Get the new IP:

wsl -d Ubuntu-24.04 --exec hostname -I

Use the .bat desktop shortcut which always fetches the current IP.

Services Will Not Start After Reboot

Check logs for errors:

journalctl -u codehero-web -n 50
journalctl -u codehero-daemon -n 50
journalctl -u mysql -n 50

Delete and Reinstall WSL Distro

To start completely fresh:

# Remove the distro (deletes all data inside)
wsl --unregister Ubuntu-24.04

# Install a fresh copy
wsl --install -d Ubuntu-24.04

Then follow the Manual Installation steps again.

WSL Uses Too Much Memory

Create or edit %UserProfile%\.wslconfig:

[wsl2]
memory=4GB
processors=2

Then restart WSL:

wsl --shutdown

Quick Reference