Windows (WSL)

Optimal OpenCode setup for Windows using Windows Subsystem for Linux

While OpenCode can run natively on Windows, Windows Subsystem for Linux (WSL) provides the best experience with superior performance, compatibility, and stability.

Why WSL is recommended:

• 10-20x faster file I/O operations
• Full POSIX compatibility for shell commands
• Seamless integration with Linux development tools
• Better terminal emulator support
• Native Git performance

Quick Start

1. Install WSL

   Open PowerShell as Administrator and run:

   wsl --install
   

   This installs:

   • WSL 2 (latest version)
   • Ubuntu Linux (default distribution)
   • Required kernel components

   Restart your computer when prompted.

2. Launch WSL

   After restart, open “Ubuntu” from the Start menu.

   Create a UNIX username and password (does not need to match Windows credentials).

3. Install OpenCode

   In the WSL terminal:

   curl -fsSL https://opencode.ai/install | bash
   

   Or use npm/pnpm/brew:

   # npm
   npm install -g opencode-cli
   
   # pnpm
   pnpm add -g opencode-cli
   
   # Homebrew
   brew install opencode
   
4. Run OpenCode

   Navigate to your project and start:

   cd /mnt/c/Users/YourName/projects/my-app
   opencode
   

WSL Installation Details

Prerequisites

• Windows 10 version 2004+ (Build 19041+) or Windows 11
• Virtualization enabled in BIOS/UEFI
• Administrator access for initial setup

Manual Installation

If wsl --install doesn’t work:

1. Enable WSL feature

   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
   
2. Enable Virtual Machine Platform

   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
   
3. Restart Windows

   Reboot is required for features to activate.

4. Download WSL kernel update

   WSL2 Kernel Update (x64)

   Install the downloaded MSI package.

5. Set WSL 2 as default

   wsl --set-default-version 2
   
6. Install Linux distribution

   Open Microsoft Store → Search “Ubuntu” → Install

   Or via command line:

   wsl --install -d Ubuntu
   

Verify Installation

# Check WSL version
wsl --list --verbose

# Expected output:
#   NAME      STATE           VERSION
# * Ubuntu    Running         2

Ensure VERSION is 2. If it shows 1, upgrade:

wsl --set-version Ubuntu 2

Accessing Windows Files

WSL mounts Windows drives under /mnt/:

File Paths

# Windows C:\ drive
/mnt/c/

# Windows D:\ drive
/mnt/d/

# Example: Windows Desktop
/mnt/c/Users/YourName/Desktop/

# Example: Documents folder
/mnt/c/Users/YourName/Documents/

cd /mnt/c/Users/YourName/projects/my-app
opencode

Performance Considerations

Cross-filesystem operations are slow.

Accessing Windows files from WSL (/mnt/c/) is significantly slower than native WSL filesystem (~/).

• Windows → WSL: ~30% slower
• WSL → Windows: ~60% slower

Performance Optimization

For best performance, store projects in the WSL filesystem:

# Clone repos into WSL home directory
cd ~
mkdir -p ~/projects
cd ~/projects
git clone https://github.com/user/repo.git
cd repo
opencode

Benchmark comparison (reading 1000 files):

• Native WSL (~/projects/): ~0.8 seconds
• Windows mount (/mnt/c/projects/): ~3.2 seconds

VS Code Remote-WSL extension can edit files in ~/projects/ seamlessly.

Architecture Patterns

Pattern 1: TUI in WSL (Recommended)

Best for: Developers who prefer terminal interfaces.

# In WSL terminal
cd ~/projects/my-app
opencode

✅ Pros:

• Best performance
• Full feature support
• Native terminal experience

❌ Cons:

• Terminal-only (no GUI)

Pattern 2: Web Client + WSL Server

Best for: Developers who prefer browser-based UIs.

1. Start web server in WSL

   opencode web --hostname 0.0.0.0 --port 3000
   
2. Open in Windows browser

   Navigate to http://localhost:3000

✅ Pros:

• Modern web UI
• Server runs in performant WSL environment
• Access from any Windows browser

❌ Cons:

• Requires browser
• Slightly higher resource usage

WSL automatically forwards localhost ports to Windows. No additional configuration needed.

Pattern 3: Desktop App + WSL Server

Best for: Users who want native desktop app with WSL performance.

1. Start server in WSL with external access

   export OPENCODE_SERVER_PASSWORD="your-secure-password"
   opencode serve --hostname 0.0.0.0 --port 4096
   

   Always set OPENCODE_SERVER_PASSWORD when using --hostname 0.0.0.0.

2. Install OpenCode Desktop on Windows

   Download from opencode.ai/download

3. Connect Desktop app to WSL server

   In OpenCode Desktop:

   1. Click server name in bottom-right
   2. Enter URL: http://localhost:4096
   3. Enter credentials (username: opencode, password: your password)

✅ Pros:

• Native desktop app experience
• Server performance benefits from WSL
• System notifications work

❌ Cons:

• Requires password authentication
• More complex setup

If localhost doesn't work

Get WSL’s IP address:

# In WSL
hostname -I
# Output: 172.20.10.5

Connect Desktop app to http://172.20.10.5:4096 instead of localhost:4096.

File Editing

VS Code Remote-WSL (Recommended)

Edit files in WSL filesystem from Windows:

1. Install VS Code on Windows

   Download from code.visualstudio.com

2. Install Remote-WSL extension

   In VS Code:

   1. Open Extensions (Ctrl+Shift+X)
   2. Search “Remote - WSL”
   3. Click Install
3. Open project from WSL

   # In WSL terminal
   cd ~/projects/my-app
   code .
   

   VS Code opens on Windows, editing files in WSL.

4. Run OpenCode in integrated terminal

   In VS Code’s terminal (Ctrl+ `):

   opencode
   

✅ Benefits:

• Edit in GUI, run in WSL
• Full IntelliSense and extensions
• Git integration
• Side-by-side with OpenCode TUI

Windows File Explorer

Access WSL files from Windows:

\\wsl$\Ubuntu\home\yourusername\projects

1. Open File Explorer
2. Type \\wsl$ in address bar
3. Navigate to your files

Editing large files via \\wsl$ can be slow. Use VS Code Remote-WSL instead.

Git Configuration

Separate Git Configs

WSL and Windows Git are separate. Configure Git in WSL:

# In WSL terminal
git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

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

SSH Keys

Generate SSH keys in WSL:

ssh-keygen -t ed25519 -C "[e-mail]"
cat ~/.ssh/id_ed25519.pub
# Copy output and add to GitHub/GitLab

WSL SSH keys are separate from Windows. You’ll need to add the new public key to GitHub/GitLab.

Terminal Recommendations

Windows Terminal (Best)

Modern terminal with tabs, GPU acceleration, and WSL integration.

Install:

• Microsoft Store: “Windows Terminal”
• Or via winget:
  winget install Microsoft.WindowsTerminal
  

Configure:

1. Open Windows Terminal
2. Settings → Startup → Default profile: Ubuntu
3. Settings → Ubuntu → Appearance → Font: “Cascadia Code NF”

Alternative: Termius, iTerm2-like

For users wanting more features:

• Tabby - Cross-platform, highly customizable
• Fluent Terminal - Modern UWP terminal

Troubleshooting

WSL won't start

Error: The virtual machine could not be started...

Fix:

1. Enable Virtualization in BIOS:
   • Restart → Enter BIOS (F2/DEL/F12)
   • Find “Virtualization Technology” or “VT-x/AMD-V”
   • Enable → Save → Reboot
2. Ensure Windows features are enabled:
   # Run as Administrator
   Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
   Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
   

Slow file operations

Symptoms: OpenCode takes minutes to start, file edits lag.

Cause: Project is on Windows filesystem (/mnt/c/).

Fix: Move project to WSL:

# Copy project to WSL
cp -r /mnt/c/Users/YourName/projects/my-app ~/projects/
cd ~/projects/my-app
opencode  # Much faster!

Cannot access WSL files from Windows

Symptoms: \\wsl$ path not found in File Explorer.

Fix:

1. Ensure WSL is running:

   wsl --list --verbose
   # Should show "Running"
   

2. Start WSL if stopped:

   wsl
   

3. Retry accessing \\wsl$\Ubuntu

Git credentials not working

Symptoms: Git push asks for password every time.

Fix: Use Windows credential manager from WSL:

git config --global credential.helper "/mnt/c/Program\\ Files/Git/mingw64/bin/git-credential-manager.exe"

Or set up SSH keys (see Git Configuration section).

OpenCode can't find Node/Python/etc.

Cause: Tool installed in Windows, not WSL.

Fix: Install tools in WSL:

# Node.js via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install --lts

# Python
sudo apt update
sudo apt install python3 python3-pip

# Docker
# Use Docker Desktop for Windows with WSL 2 backend

Port already in use

Symptoms: opencode serve fails with “port 4096 already in use”.

Cause: Windows process using the port.

Fix:

# In PowerShell (as Administrator)
netstat -ano | findstr :4096
# Note the PID in last column

taskkill /PID <PID> /F

Or use a different port:

opencode serve --port 4097

Advanced: Docker in WSL

Docker Desktop Integration

1. Install Docker Desktop for Windows

   Download from docker.com

2. Enable WSL 2 backend

   Docker Desktop → Settings → General → “Use the WSL 2 based engine” ✓

3. Enable Ubuntu integration

   Docker Desktop → Settings → Resources → WSL Integration → Enable Ubuntu ✓

4. Verify in WSL

   docker --version
   docker run hello-world
   

Now OpenCode can use Docker for:

• Running MCP servers in containers
• Containerized development environments
• Building and testing Docker images

Performance Tuning

Increase WSL Memory Limit

By default, WSL uses 50% of total RAM. For large projects:

1. Create .wslconfig file

   # In PowerShell
   notepad $env:USERPROFILE\.wslconfig
   
2. Add configuration

   [wsl2]
   memory=8GB        # Increase for large projects
   processors=4      # Match CPU cores
   swap=2GB
   localhostForwarding=true
   
3. Restart WSL

   wsl --shutdown
   wsl
   

Disable Windows Defender for WSL

Windows Defender can slow down file operations:

1. Open Windows Security

   Start → “Windows Security” → Virus & threat protection

2. Add exclusions

   Manage settings → Exclusions → Add or remove exclusions

   Add:

   • %USERPROFILE%\AppData\Local\Packages\CanonicalGroupLimited.*
   • \\wsl$\Ubuntu\home\<yourusername>\projects

Only exclude trusted directories. Do not disable Defender entirely.

Migration: Windows → WSL

Moving existing projects to WSL:

1. Identify project locations

   # In PowerShell
   dir C:\Users\YourName\projects
   
2. Copy to WSL

   # In WSL
   mkdir -p ~/projects
   cp -r /mnt/c/Users/YourName/projects/* ~/projects/
   
3. Update Git remotes (if needed)

   cd ~/projects/my-app
   git remote -v  # Verify URLs are correct
   
4. Reinstall dependencies

   # For Node projects
   rm -rf node_modules package-lock.json
   npm install
   
   # For Python projects
   rm -rf venv/
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

Leave originals on Windows until you’ve verified everything works in WSL.

Best Practices

Store projects in WSL

Use ~/projects/ instead of /mnt/c/ for 3-4x faster performance.

Use Windows Terminal

Better performance, tabs, and customization than Command Prompt or PowerShell.

VS Code Remote-WSL

Edit files seamlessly while benefiting from WSL’s speed.

Docker Desktop WSL 2 backend

Native container performance with Windows UI.

Next Steps

Server Configuration

Advanced server setup for WSL environments.

Network Setup

Configure proxies and certificates in WSL.

Troubleshooting

Diagnose and fix WSL-specific issues.

VS Code Integration

Connect OpenCode with VS Code in WSL.