How to Run OpenCode on Windows: Native Install or WSL

Quick answer: yes, opencode runs on Windows

# PowerShell - install opencode globally with npm
npm install -g opencode-ai

# Verify the install
opencode --version

# Start opencode inside a project folder
opencode

That is the whole native path on Windows: Node.js plus one npm install. You do not need WSL just to run opencode. WSL becomes the better option only when your project itself depends on Linux tooling, which we cover further down.

opencode is SST's open-source terminal agent. For the exact installation commands and the latest options, check the official opencode site and the opencode GitHub repository, since the install method evolves over time. This guide mirrors our Claude Code on Windows guide and the Codex CLI on Windows guide, but for opencode.

What you need before installing

• Windows 10 or Windows 11, 64-bit. opencode is a command-line tool you run from a terminal.
• Node.js (a recent LTS release) and npm, which ships with Node.js. This is what the native Windows install relies on.
• A terminal: Windows Terminal or PowerShell, both of which come with Windows. PowerShell is fine for installing and running opencode.
• An account or API key with at least one model provider (Anthropic, OpenAI, Google or a local model setup). opencode is provider-agnostic, so it connects to whichever provider you choose the first time you run it.

Native Windows install step by step

Once Node.js is in place, installing opencode natively on Windows takes about a minute:

• Open Windows Terminal or PowerShell. You do not need to run it as administrator.
• Confirm Node.js is ready with node --version and npm --version.
• Install opencode globally: npm install -g opencode-ai
• Close and reopen the terminal so the new command is on your PATH.
• Run opencode --version to confirm it is installed.

To update opencode later, run the same npm install command again, which pulls the latest published version:

npm install -g opencode-ai@latest

First run: connecting a provider

• Open a terminal in a project folder and type opencode.
• Connect a provider (for example with opencode auth login): pick Anthropic, OpenAI, Google or another provider, then sign in or paste an API key.
• Once the provider is connected, ask opencode something about your code and let it work.

After you connect a provider once, opencode stores those credentials, so the next time you run opencode in any folder it starts straight away. Its global config lives under ~/.config/opencode in your user profile, and each terminal you open is its own independent opencode session. The exact auth command can change, so check the official opencode docs if the flow looks different on your version.

Running opencode in WSL (and when to prefer it)

WSL (Windows Subsystem for Linux) lets you run a real Linux environment inside Windows. opencode runs there exactly the same way, and there are two scenarios where WSL is the better choice:

• Your project depends on Linux tooling. If your build chain, scripts or dependencies assume Linux, run opencode where your project actually runs so paths and shell commands match.
• You want Linux-native command behaviour. Some sandboxing and shell commands only line up properly inside a Linux environment, which on Windows means WSL 2.

To run opencode inside WSL, open your WSL distribution terminal (not PowerShell), make sure Node.js and npm are installed inside that Linux environment, and install opencode there:

# Inside your WSL (Linux) terminal
npm install -g opencode-ai

# Then run it from your project
opencode

One thing to watch in WSL: connecting your provider from a Linux terminal sometimes shows you a code or URL to complete in your Windows browser instead of redirecting automatically. If that happens, finish the flow in the browser and return to the terminal, and keep your project files inside the Linux filesystem for the best performance.

Native Windows vs WSL: which one should you use?

• Native Windows: best for Windows-native projects (.NET, Unity, general web dev with Windows tooling). Simplest setup, just Node.js plus an npm install, and it runs straight from PowerShell.
• WSL 2: best for Linux toolchains and Linux-native command behaviour. Your files live in the Linux filesystem, so Linux-first projects behave exactly as they would on a server.
• WSL 1: only if WSL 2 is not available on your machine. It has known issues running native binaries, so prefer WSL 2 whenever you can.

If you are unsure, start native. It is the path of least friction on Windows and you can always add a WSL install later; both can coexist on the same machine, and you can even point different opencode terminals at different setups.

Common Windows errors and how to fix them

• "opencode is not recognized as a command": the global npm bin folder is not on your PATH, or you did not reopen the terminal after installing. Close and reopen PowerShell, and confirm npm config get prefix points at a folder that is on your PATH.
• "npm is not recognized": Node.js is not installed or not on your PATH. Install Node.js LTS, reopen the terminal, and check node --version.
• EACCES or permission errors on npm install -g: your global npm folder is not user-writable. Reinstall Node.js with the official Windows installer or set an npm prefix under your user profile instead of forcing it with admin rights.
• Corporate proxy or SSL errors during install: configure npm with your proxy settings, or run the install from a network that is not behind the proxy, then update later.
• Provider authentication errors: usually a wrong or missing API key, or the wrong provider selected. Re-run the auth flow, and check which provider is configured in ~/.config/opencode/opencode.json.
• opencode behaves oddly with Windows paths or shell commands: your project likely expects a Unix shell. Run opencode inside WSL for that project so paths and commands match.

For anything else, the official opencode repository tracks known issues and the current install instructions, which is the source of truth as the tool evolves.

Running multiple opencode sessions on Windows

Once opencode is working, the next bottleneck shows up fast: one terminal means one task at a time. You hand opencode something to do, and then you wait. Most developers end up opening several terminal tabs and losing track of which agent finished, which one is waiting for an approval, and what each one changed.

That is the problem CodeAgentSwarm solves, and it is a native desktop app for both Windows and macOS. It runs your opencode sessions inside a visual workspace, so Windows developers get a real GUI plus multiple opencode terminals side by side, with desktop notifications when an agent finishes or needs input, searchable history across every session, and a live diff of what each terminal changed. It also reads opencode's local sessions, so past conversations stay searchable and you can resume them.

If you want to go down that path, these guides are the natural next step: running an opencode agent swarm, running multiple opencode sessions, and the broader AI CLI agent swarm overview across every CLI.

Conclusion

Running opencode on Windows is straightforward: install Node.js, run one npm install, and start it from PowerShell. Native is the right default for most Windows developers; WSL 2 is there when your project depends on Linux tooling or you want Linux-native command behaviour. Either way, you connect a provider once and opencode remembers it.

Install it, connect your provider once, and when a single terminal stops being enough, CodeAgentSwarm gives you a native Windows GUI to run several opencode agents in parallel without losing the plot.