Tools & Configuration

WSL Setup Guide

This guide covers setting up Windows Subsystem for Linux (WSL2) for development with the Sigao AI DevKit, including the bootstrap method and optimizations for AI/web development.

WSL Setup Guide

This guide covers setting up Windows Subsystem for Linux (WSL2) for development with the Sigao AI DevKit, including the bootstrap method and optimizations for AI/web development.

Table of Contents

Prerequisites

  • Windows 10 version 2004+ (Build 19041+) or Windows 11
  • Administrator access
  • ~4GB free disk space per distribution
  • Virtualization enabled in BIOS

🚀 Quick Start with Bootstrap

The fastest way to set up a complete development environment in WSL:

1. Create a Fresh WSL Instance

# From PowerShell as Administrator
wsl --install Ubuntu-24.04 --name claude-code --location C:\wsl-distros\claude-code
wsl -d claude-code

2. Inside WSL, Install npm

sudo apt update && sudo apt install -y nodejs npm

3. Run the Bootstrap

npx @sigaostudios/bootstrap

This will:

  • ✅ Install Node.js (if needed)
  • ✅ Install GitHub CLI
  • ✅ Authenticate with GitHub
  • ✅ Configure npm for private packages
  • ✅ Launch the Sigao installer

⚠️ Common WSL PATH Issue

If you see "CMD.EXE was started" errors, you have Windows tools in your PATH from:

  • fnm (Fast Node Manager)
  • nvm-windows
  • Scoop
  • Windows Node installations

Solution: Use Linux-specific npm:

/usr/bin/npx @sigaostudios/bootstrap

Installing WSL2

Quick Install (Recommended)

# Run in PowerShell as Administrator
wsl --install

# This installs WSL2 with Ubuntu 22.04 LTS by default

Custom Installation

# List available distributions
wsl --list --online

# Install specific Ubuntu version
wsl --install Ubuntu-24.04

# Install with custom name and location
wsl --install Ubuntu-24.04 --name dev-env --location D:\wsl

Choosing an Ubuntu Distribution

Available Ubuntu Versions

DistributionVersionSupport UntilBest ForInstall Command
Ubuntu 24.04 LTSNoble NumbatApril 2029Latest features, Sigao DevKitwsl --install Ubuntu-24.04
Ubuntu 22.04 LTSJammy JellyfishApril 2027Stability, CUDA/ML workwsl --install Ubuntu-22.04
Ubuntu 20.04 LTSFocal FossaApril 2025Legacy projectswsl --install Ubuntu-20.04

Recommendations by Use Case

🤖 For AI Development with Sigao

Recommended: Ubuntu 24.04 LTS

  • Latest Claude CLI support
  • Modern Node.js for workpackages
  • Best performance optimizations
  • Long-term support

🧠 For ML/Data Science

Recommended: Ubuntu 22.04 LTS

  • Best CUDA/cuDNN compatibility
  • Stable Python ecosystem
  • Well-tested with TensorFlow/PyTorch

💻 For Web Development

Recommended: Ubuntu 24.04 LTS

  • Latest Node.js/npm versions
  • Modern toolchain support
  • Better container integration

Initial Setup

1. First Boot Configuration

When you first launch Ubuntu:

# Create your UNIX username (lowercase, no spaces)
# Set a password (won't show while typing)

2. Bootstrap Method (Recommended)

# Install npm if needed
sudo apt update && sudo apt install -y nodejs npm

# Run bootstrap
npx @sigaostudios/bootstrap

# Or if you have PATH issues
/usr/bin/npx @sigaostudios/bootstrap

3. Alternative: Sigao CLI Direct Install

# Install Sigao CLI globally
npm install -g @sigaostudios/sigao-cli

# Run interactive setup
sigao

# Or install everything
sigao --yes

4. Configure Windows Terminal

  1. Install Windows Terminal from Microsoft Store
  2. Set Ubuntu as default profile: Settings → Startup → Default profile
  3. Install a Nerd Font for icons:
    • Download from Nerd Fonts
    • Recommended: MesloLGS NF, FiraCode NF, or JetBrainsMono NF
    • Set in Terminal: Settings → Profiles → Ubuntu → Appearance → Font face

Common WSL Issues

Windows PATH Contamination

Problem: Windows npm/node interfering with Linux tools

Solution 1: Disable Windows PATH in WSL

# Add to /etc/wsl.conf
sudo nano /etc/wsl.conf

Add:

[interop]
appendWindowsPath=false

Then restart WSL:

wsl --shutdown

Solution 2: Use absolute Linux paths

/usr/bin/npm install
/usr/bin/npx @sigaostudios/bootstrap

npm/npx Not Found

# Install Node.js and npm
sudo apt update && sudo apt install -y nodejs npm

# Verify installation
which npm  # Should show /usr/bin/npm

DNS Resolution Issues

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

# Permanent fix in /etc/wsl.conf
[network]
generateResolvConf=false

Locale Warnings

sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8

Performance Optimization

1. WSL Configuration

Create /etc/wsl.conf:

sudo nano /etc/wsl.conf

Add:

[boot]
systemd=true

[interop]
appendWindowsPath=false  # Prevents Windows PATH pollution

[network]
generateHosts=true
generateResolvConf=true

[user]
default=yourusername

2. Memory and CPU Limits

Create C:\Users\YourUsername\.wslconfig:

[wsl2]
memory=8GB  # Adjust based on your system
processors=4  # Adjust based on your CPU
swap=2GB
localhostForwarding=true

# For better file performance
[experimental]
autoMemoryReclaim=gradual
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

3. File System Performance

DO: Keep projects in Linux filesystem

# Good performance
~/projects/myapp
cd ~
sigao work package.json --output-dir ./myapp

# Poor performance (Windows filesystem)
/mnt/c/Users/YourName/projects/myapp

Move existing projects:

# From Windows to WSL
cp -r /mnt/c/Users/YourName/projects ~/

Integration with Windows

VS Code Integration

# Install VS Code Server (first time only)
code .

# Open specific file
code myfile.js

# Open in Windows VS Code from WSL
code --remote wsl+Ubuntu-24.04 ~/projects

Git Credential Manager

The Sigao setup automatically configures this, but manually:

# Use Windows credentials in WSL
git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

Accessing Files

WSL → Windows:

# Open current directory in Windows Explorer
explorer.exe .

# Copy file to Windows Desktop
cp file.txt /mnt/c/Users/YourName/Desktop/

Windows → WSL:

  • File Explorer: \\wsl$\Ubuntu-24.04\home\username
  • Or type \\wsl$ in Explorer address bar

Browser Integration

The Sigao setup includes wslview for opening URLs:

# Open URL in Windows browser
wslview https://github.com

# Alias included
open https://google.com

Docker Integration

Option 1: Docker Desktop (Recommended)

  1. Install Docker Desktop for Windows
  2. Enable: Settings → Resources → WSL Integration → Enable for your distro
  3. Docker commands work in WSL without native install

Option 2: Native Docker in WSL

# Install via Sigao
sigao -c docker

# Or manually
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Best Practices

  1. Use WSL2 (not WSL1) for better performance
  2. Keep code in Linux filesystem for 10x better I/O performance
  3. Use Windows Terminal with a Nerd Font
  4. Disable Windows PATH to avoid conflicts
  5. Regular updates: sudo apt update && sudo apt upgrade
  6. Use bootstrap for consistent setup
  7. Restart after config changes: wsl --shutdown

Useful Commands

PowerShell Commands

# List distributions
wsl --list --verbose

# Set default distro
wsl --set-default Ubuntu-24.04

# Shutdown all WSL
wsl --shutdown

# Export/backup distro
wsl --export Ubuntu-24.04 backup.tar

# Import distro
wsl --import MyUbuntu C:\WSL backup.tar

# Uninstall distro (WARNING: deletes all data)
wsl --unregister Ubuntu-24.04

# Run command in specific distro
wsl -d Ubuntu-24.04 ls -la

# Check WSL version
wsl --version

Inside WSL

# System info
uname -a
lsb_release -a

# Resource usage
df -h  # Disk space
free -h  # Memory
htop  # Process monitor (installed by Sigao)

# WSL utilities
wslpath -w ~/projects  # Convert to Windows path
wslpath -u 'C:\Users'  # Convert to Linux path

Advanced Tips

Multiple Distributions

# Install multiple versions
wsl --install Ubuntu-22.04
wsl --install Ubuntu-24.04

# Create specialized environments
wsl --install Ubuntu-24.04 --name ai-dev
wsl --install Ubuntu-24.04 --name web-dev

# Switch between them
wsl -d ai-dev
wsl -d web-dev

Custom Initialization

Create ~/.wsl_init:

#!/bin/bash
# Custom WSL initialization

# Start services
sudo service postgresql start
sudo service redis-server start

# Set environment
export PROJECT_HOME=~/projects
cd $PROJECT_HOME

Then in ~/.bashrc:

# Run WSL init if exists
[ -f ~/.wsl_init ] && source ~/.wsl_init

Troubleshooting Workpackages

If workpackages fail in WSL:

# Ensure Claude CLI is installed
sigao -c claude

# Check npm configuration
npm config list

# Verify GitHub auth
gh auth status

# Re-run bootstrap if needed
npx @sigaostudios/bootstrap

Next Steps

Need help? Check our Troubleshooting guide or open an issue.

CLI Tools

Modern command-line tools and utilities optimized for AI development workflows.

Templates & Examples

Jumpstart your projects with ready-to-use templates and real-world examples.