Skip to main content
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” → InstallOr 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/: 
# 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/

​
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
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

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
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

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 "you@example.com"

# 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 "you@example.com"
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:

​
Troubleshooting

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
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!
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
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).
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
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 exclusionsAdd:
  • %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.