OpenCode is a free, open-source terminal coding agent, and on Windows it’s happiest in WSL — a clean Unix-like shell where its config, providers, and file operations all behave as the docs assume. This guide installs and runs OpenCode in WSL, including adding a cheap model provider, with the WSL details worth knowing.
If WSL isn’t installed yet, start with the WSL install guide. For the provider config in depth, see OpenCode custom providers.
Step 1: Node in WSL
OpenCode installs via npm, so install Node inside WSL with nvm:
sudo apt update && sudo apt install -y curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --ltsStep 2: Install OpenCode
npm install -g opencode-ai
opencode --versionStep 3: Add a cheap provider
Add a provider to opencode.json using the OpenAI-compatible adapter. DeepSeek example:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"deepseek": {
"npm": "@ai-sdk/openai-compatible",
"name": "DeepSeek",
"options": {
"baseURL": "https://api.deepseek.com/v1",
"apiKey": "{env:DEEPSEEK_API_KEY}"
},
"models": { "deepseek-chat": { "name": "DeepSeek Chat" } }
}
},
"model": "deepseek/deepseek-chat"
}Export the key in your profile:
echo 'export DEEPSEEK_API_KEY="sk-your-key"' >> ~/.bashrc
source ~/.bashrc
opencodeSwap the block for GLM, Kimi, MiniMax, or StepFun.
Step 4: Work in the Linux file system
For big repos, copy the project into your Linux home so OpenCode’s file operations stay fast:
cp -r /mnt/c/Users/YourName/myproject ~/myproject
cd ~/myproject
opencodeSee access your Windows files from WSL.
OpenCode in WSL essentials
| nvm install --lts | Node inside WSL |
|---|---|
| npm i -g opencode-ai | Install OpenCode |
| opencode.json in Linux home | Provider config |
| {env:VAR} + key in ~/.bashrc | Cheap model auth |
| project in ~ | Faster file operations |
WSL gotchas
opencode: command not found— reopen the shell after install.- Provider not found — the
providerkey must match themodelprefix. - Config not loading — check for a stray
OPENCODE_CONFIGvariable overriding it. - Slow on big repos — move the project into your Linux home.
OpenCode on WSL checklist
- WSL installed; Node via nvm inside WSL
- OpenCode installed (npm i -g opencode-ai)
- Provider block in opencode.json (Linux home)
- API key exported in ~/.bashrc
- Active project in Linux home; launched with opencode
Wrapping up
On Windows, install OpenCode in WSL: Node via nvm, npm i -g opencode-ai, a provider block in opencode.json, and your key in ~/.bashrc. Keep config and active projects in your Linux home for clean permissions and speed. From there it runs on any cheap model you configure.
For the provider details, see OpenCode custom providers and pick a backend like DeepSeek + OpenCode.
