Windows (WSL) - OpenCode

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

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.

Launch WSL

After restart, open “Ubuntu” from the Start menu.Create a UNIX username and password (does not need to match Windows credentials).

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

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:

Enable WSL feature

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

Enable Virtual Machine Platform

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

Restart Windows

Reboot is required for features to activate.

Download WSL kernel update

WSL2 Kernel Update (x64)Install the downloaded MSI package.

Set WSL 2 as default

wsl --set-default-version 2

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

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.

Start web server in WSL

opencode web --hostname 0.0.0.0 --port 3000

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.

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.

Install OpenCode Desktop on Windows

Download from opencode.ai/download

Connect Desktop app to WSL server

In OpenCode Desktop:

Click server name in bottom-right
Enter URL: http://localhost:4096
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:

Install VS Code on Windows

Download from code.visualstudio.com

Install Remote-WSL extension

In VS Code:

Open Extensions (Ctrl+Shift+X)
Search “Remote - WSL”
Click Install

Open project from WSL

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

VS Code opens on Windows, editing files in WSL.

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

Open File Explorer
Type \\wsl$ in address bar
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:

Open Windows Terminal
Settings → Startup → Default profile: Ubuntu
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:

Enable Virtualization in BIOS:
- Restart → Enter BIOS (F2/DEL/F12)
- Find “Virtualization Technology” or “VT-x/AMD-V”
- Enable → Save → Reboot

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:

Ensure WSL is running:

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

Start WSL if stopped:
```
wsl
```
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

Install Docker Desktop for Windows

Download from docker.com

Enable WSL 2 backend

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

Enable Ubuntu integration

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

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:

Create .wslconfig file

# In PowerShell
notepad $env:USERPROFILE\.wslconfig

Add configuration

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

Restart WSL

wsl --shutdown
wsl

Disable Windows Defender for WSL

Windows Defender can slow down file operations:

Open Windows Security

Start → “Windows Security” → Virus & threat protection

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:

Identify project locations

# In PowerShell
dir C:\Users\YourName\projects

Copy to WSL

# In WSL
mkdir -p ~/projects
cp -r /mnt/c/Users/YourName/projects/* ~/projects/

Update Git remotes (if needed)

cd ~/projects/my-app
git remote -v  # Verify URLs are correct

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.

Get Started

Core Concepts

Configuration

Integrations

Extensibility

Interfaces

Advanced

Enterprise

Documentation Index

​Quick Start

​WSL Installation Details

​Prerequisites

​Manual Installation

​Verify Installation

​Accessing Windows Files

​Performance Considerations

​Architecture Patterns

​Pattern 1: TUI in WSL (Recommended)

​Pattern 2: Web Client + WSL Server

​Pattern 3: Desktop App + WSL Server

​File Editing

​VS Code Remote-WSL (Recommended)

​Windows File Explorer

​Git Configuration

​Separate Git Configs

​SSH Keys

​Terminal Recommendations

​Windows Terminal (Best)

​Alternative: Termius, iTerm2-like

​Troubleshooting

​Advanced: Docker in WSL

​Docker Desktop Integration

​Performance Tuning

​Increase WSL Memory Limit

​Disable Windows Defender for WSL

​Migration: Windows → WSL

​Best Practices

Store projects in WSL

Use Windows Terminal

VS Code Remote-WSL

Docker Desktop WSL 2 backend

​Next Steps

Server Configuration

Network Setup

Troubleshooting

VS Code Integration

Build docs developers (and LLMs) love

Quick Start

WSL Installation Details

Prerequisites

Manual Installation

Verify Installation

Accessing Windows Files

Performance Considerations

Architecture Patterns

Pattern 1: TUI in WSL (Recommended)

Pattern 2: Web Client + WSL Server

Pattern 3: Desktop App + WSL Server

File Editing

VS Code Remote-WSL (Recommended)

Windows File Explorer

Git Configuration

Separate Git Configs

SSH Keys

Terminal Recommendations

Windows Terminal (Best)

Alternative: Termius, iTerm2-like

Troubleshooting

Advanced: Docker in WSL

Docker Desktop Integration

Performance Tuning

Increase WSL Memory Limit

Disable Windows Defender for WSL

Migration: Windows → WSL

Best Practices

Next Steps