Install OpenCode Desktop and CLI on Windows to Use Free AI Models

Key points

OpenCode is an AI coding tool that helps you explore a project’s code and work on development tasks. On Windows, you can use the desktop app, which runs in its own window, or the CLI, which runs from a terminal. This guide covers both installation methods and how to check that the first response works.

Download the Windows installer for the desktop app from the official page. For the CLI, this guide uses npm, which comes with Node.js. OpenCode’s official documentation also recommends WSL on Windows, so this guide includes that option for people who need a Linux development environment. Installation guide, Windows guide

Choosing between the desktop app and CLI

CLI means command-line interface. Running opencode opens an interactive screen in your terminal, called a TUI. The desktop app runs in a separate window. Confirm that the app opens and that PowerShell can find the CLI command separately. CLI guide

If you plan to use both, follow the desktop and CLI sections in order. If you only need one, follow that installation path and the completion checks that apply to it.

Before you begin

• In Windows, open Settings → System → About → System type and check your processor architecture. The official desktop download lists Windows x64. That listing alone does not establish native support for ARM PCs.
• Installing the CLI with npm requires Node.js and npm. You do not need Node.js just to run the desktop installer.
• Check the sign-in method and terms for the AI provider you plan to use. Installing the program and having access to a model are separate things. Depending on the provider and model, usage may cost money.
• Start with a practice folder or a copy of your project instead of important source files. Review proposed file changes and commands before applying them.

You can compare the official download page with the official repository. This guide does not assume that the two package names refer to the same product version or compatible replacements.

Verification environment

The version output and screen checks below are steps for you to perform. They do not claim that installation was tested on a particular PC.

Main content

1. Install the OpenCode desktop app on Windows

Download the official installer

1. Open OpenCode Downloads in your browser.
2. Under OpenCode Desktop, choose the Windows (x64) download.
3. When the download finishes, find the installer in File Explorer’s Downloads folder.

The official README lists the Windows installer filename as opencode-desktop-windows-x64.exe. The filename may change between releases, so use the official download link instead of searching for a copy on an unrelated site. The README describes the desktop app as a beta. Desktop installation

Install and open the app

Run the downloaded installer and review the destination folder and options shown by the setup wizard. When installation finishes, search for OpenCode in the Start menu and open it. Button names and options may change between releases.

If Windows displays a security warning, first check the download source and the publisher or signature in the file properties. If you cannot confirm the file’s source, stop and download it again from the official link.

When the app opens, choose the option to open a project or folder and select a practice folder. If the app shows a provider connection or model-selection screen, follow the sign-in steps for your provider. Use the screen in your installed version as the reference because menu names can change.

After choosing a project and model, use the first question in Step 4 to check for a response. If it works, you have confirmed the desktop app is ready for basic use. Continue to the CLI installation if you also need to run commands in PowerShell.

Choose a model in the desktop app

A model is the AI that interprets your request and produces an answer or code. A provider is the service that makes that model available. Choose a model, then check its response with a short question.

Click the current model name and down arrow at the lower left of the input box. In the screenshot below, that button is Exo Free, outlined in red. Hovering over it shows the hint Choose model. Click the model name rather than the adjacent Default setting.

When the Select model window opens, click a model in the list. The screenshot below highlights Muse Spark 1.3 as an example. The selection checkmark is still next to Exo, so the highlighted item should not be mistaken for the selected model. To use Muse Spark 1.3, click it and then check whether the model name below the input box changes.

Model details may include Provider, Inputs, Reasoning, and Context. Check that the model supports the input types you need. A larger context limit alone does not mean that answers will be more accurate.

The Free label reflects the screenshot at the time it was captured. Available models and terms can change, so check the current selection screen. If a model is not listed, do not keep reinstalling to find the same name; choose a model that is currently available. To add another provider, choose one in the Add more models from popular providers area at the bottom of the window and follow its sign-in steps.

After selecting a model, check the name below the input box and send the first question in Step 4. A changed model name and a successful response are separate checks. These screenshots illustrate how to choose a model; they do not recommend a specific model or compare its performance.

2. Install the OpenCode CLI on Windows

Set up Node.js and npm

From the official Node.js download page, choose the Windows LTS installer. Install the file that matches your PC’s architecture and include npm. When installation finishes, close existing terminals and open a new Windows Terminal or PowerShell window.

Run the following commands in Windows PowerShell. Move to your user folder, then check that Node.js and npm each print a version. If cd fails, do not run the following commands.

cd -LiteralPath $env:USERPROFILE -ErrorAction Stop
node --version
npm.cmd --version

Both commands must print a version before you continue. npm.cmd calls npm’s Windows command file directly from PowerShell. This can also help when the shell reports an execution-policy error for npm.ps1.

Install the OpenCode package

Run the following command in the same Windows PowerShell window. The -g option installs the package to npm’s global location instead of adding it as a dependency of the current project.

cd -LiteralPath $env:USERPROFILE -ErrorAction Stop
npm.cmd install -g opencode-ai

The package name appears in the Windows installation section of the official Intro. When the command finishes without an error, open a new PowerShell window and check the installation.

cd -LiteralPath $env:USERPROFILE -ErrorAction Stop
opencode --version
opencode --help

If the version and help text appear, the terminal can find the CLI executable. This does not yet confirm provider authentication or a model response. If the command cannot be found or a script-execution error appears, see Step 6.

Before opening a project for the first time, run opencode --version and opencode --help to check that the installed CLI responds. These outputs confirm that the CLI runs; they do not guarantee that the interactive screen or project database is healthy. If it hangs or returns an error, do not keep repeating the same command or reset the data. Follow the troubleshooting steps below.

3. Start the CLI in a project and connect a provider

Create a project folder in the current folder

For a first practice project, create a folder named project1 inside the current folder and move into it. project1 is an example name. You can replace it with the name you want, but use the same name in the create, move, and launch commands.

Run these commands in Windows PowerShell or a local PowerShell terminal in VS Code. First check that the terminal is in the parent folder where you want to create project1. As in the screenshot, you can start in your user folder, or move to another working folder first. mkdir creates the child folder and cd moves into it.

mkdir project1
cd project1

The screenshot shows project1 created under C:\Users\shopb. The final prompt changes to PS C:\Users\shopb\project1>, which confirms the current location. Your Windows username and parent path may differ.

If a command fails, stop before running the next line and check the path and error. If project1 already exists, inspect it and move into it; do not recreate or delete it. To use an existing project, skip folder creation and copy its full path from File Explorer’s address bar.

Run OpenCode from the project folder

Check that the current terminal location is inside project1, then run OpenCode. If you opened a new terminal or are using an existing project, adjust the cd path to that project’s folder. If the directory change fails, do not run OpenCode.

pwd
opencode

When the interactive screen opens, enter the following command in the OpenCode input box. Do not enter it in PowerShell.

/connect

Choose a provider from the list and follow the sign-in or API-key steps shown on screen. Enter credentials only in the field provided by the provider; do not put them in project files or conversations you plan to share. Then choose a model. Connect a provider

You can also run opencode auth login from the terminal after exiting OpenCode. Use opencode auth list to see configured providers. A provider appearing in the list does not by itself confirm that a model request succeeds. CLI authentication commands

Choose a model in the CLI

After connecting a provider, enter this command in the OpenCode interactive input box and choose a model. The CLI list may look different from the desktop screen above. Official model-selection guide

/models

The command menu appears with /models selected. Press Enter to open the model list.

Choose an available model from the list. In the example below, Muse Spark 1.3 Free is selected and highlighted. The list and free labels can vary with the provider connection, account access, and version. A Free label does not guarantee that the same terms or limits will remain available; check the provider’s current terms.

After choosing a model, a variant-selection screen may appear. You can keep Default or choose another setting in the list. A variant is an inference setting for the same model. The screenshot shows minimal, low, medium, high, and xhigh, but available choices vary by model and provider. If you are unsure what a setting means, keep Default. Model variants

After making your selections, check the current model name below the input box. In the next screenshot, Muse Spark 1.3 Free appears as the current model. This confirms that the selection is displayed; it does not verify a model response or the quality of its work.

Confirm that the selected model appears on screen, then send the first question in the next section. If the model is missing from the list, check the provider connection and your account’s access to that model.

4. Check the first response

In the desktop app or CLI input box, enter a request like this:

Briefly describe the top-level folders and the roles of the main files in the currently open project.
Do not modify files or run installation commands. List any items you cannot read separately.

After sending the request, review the response about the project tree and main files. As in the next screenshot, check whether OpenCode distinguishes files or contents it could not read. Do not treat a role inferred from a filename alone, such as admin-*.js, as confirmed fact. Open the actual file or ask a follow-up question.

Check that the response matches the actual project name and file structure. If you see an authentication, usage-limit, billing, or model-access error, use the message to check the provider settings. An interactive screen opening and a model returning a response are separate checks.

If the project1 folder you just created is empty, OpenCode may report that it contains no files. Check that it accurately describes the empty folder, and distinguish that from a response describing files that do not exist yet.

After confirming the first response, you can use /init to create project guidance. This command analyzes the project and creates an AGENTS.md file, so it is not required to verify installation. If an AGENTS.md already exists, preserve its contents and review the changes after running the command. Initialize a project

5. Optional: install the CLI in WSL

WSL lets you use a Linux environment within Windows. OpenCode’s documentation recommends WSL on Windows for compatibility with development tools and terminal features. You do not need to install the native Windows CLI first. If WSL is not installed, follow Microsoft’s WSL installation guide to set up a Linux distribution and user account.

Run the following in a Linux terminal such as Ubuntu in WSL, not in PowerShell. The official install script is downloaded and run with Bash, so check the URL before executing it.

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

When installation finishes, open a new WSL terminal and check the version.

cd ~ && opencode --version

If your project is at ~/code/my-app in WSL, start it like this. Replace the example with your actual project path. Keep && so OpenCode runs only if changing directories succeeds.

cd ~/code/my-app && opencode

In a typical WSL setup, Windows path C:\Projects\my-app is available at /mnt/c/Projects/my-app. The official guide also suggests placing the project in the WSL filesystem for smoother work. Windows and WSL have separate installation paths and settings, so do not assume that installation or authentication in one environment applies in the other. WSL setup and Windows file access

6. Troubleshoot common installation and startup problems

PowerShell cannot find npm or OpenCode

If you just installed the CLI, close the terminal completely and open it again. In Windows PowerShell, check the current installation location.

cd -LiteralPath $env:USERPROFILE -ErrorAction Stop
Get-Command node,npm.cmd,opencode -All -ErrorAction SilentlyContinue
npm.cmd prefix -g
npm.cmd list -g --depth=0

Check whether opencode-ai appears in the package list. On Windows, npm’s global executable links are in its global prefix folder, which must be included in PATH for commands to work by name. Check the actual folder printed by npm.cmd prefix -g in the Windows user Path environment variable. When changing it, add only the needed entry without removing existing values, then reopen the terminal. npm folder structure

PowerShell blocks a ps1 file

If the error mentions npm.ps1 or opencode.ps1 and an execution policy, try calling the Windows command files directly.

cd -LiteralPath $env:USERPROFILE -ErrorAction Stop
npm.cmd --version
opencode.cmd --version

If these commands work, you can run opencode.cmd instead of opencode from the project folder. If PowerShell cannot find the .cmd file either, check the installation and PATH first. This procedure does not require changing the system-wide execution policy.

The terminal turns black and appears to hang

When run without arguments, the OpenCode CLI opens an interactive screen (TUI) in the terminal. The screen may briefly turn black while switching modes, but a screen that remains blank and does not respond is not a normal running state. A black screen alone does not identify whether the cause is terminal rendering, the database, or a service. CLI guide

First press Ctrl+C to stop the current process. If it does not respond, open a new PowerShell window and check which executable is being used and its version.

Get-Command opencode -All | Select-Object CommandType, Source
opencode --version
opencode --help

The available subcommands can differ between OpenCode versions. For example, in the user’s 1.18.35 environment, opencode service status displayed the general help instead of a service status. That output does not mean the service command is supported in this version. If you are advised to run service status or service restart, first check that opencode --help actually lists that command. Help output from an unsupported command cannot diagnose a background service.

To check whether the issue is specific to the terminal display, try the same project in a new PowerShell tab in Windows Terminal. If the screen goes black again, press Ctrl+C and reproduce the issue with logs enabled.

cd -LiteralPath "$env:USERPROFILE\project1"
opencode --print-logs --log-level DEBUG

This example uses project1 under your user folder. If you use another location or an existing project, change the cd path to that project. Remove API keys or tokens from logs before sharing them. The current official troubleshooting guide recommends checking logs and using --print-logs to display them in the terminal. OpenCode troubleshooting

The error says Database is not empty and has no session table

If this database error appears, do not treat it as only a TUI color or display issue. It indicates that OpenCode could not find an expected session table in the storage it is using. A version change, data shared between different installations, or an interrupted previous run could be investigation leads, but the error alone does not establish the cause.

In this case, do not repeatedly run opencode --mini, opencode web, or restart commands. The same storage may produce the same error, and repeated runs can make the diagnosis harder. OpenCode’s data folder or database may contain user data and credentials, so do not delete, reset, or overwrite it.

Collect the following read-only information in PowerShell.

Get-Command opencode -All | Select-Object CommandType, Source
Get-ChildItem Env:OPENCODE* | Select-Object Name
opencode debug --help

Get-Command shows duplicate installations and executable paths. The environment-variable command prints names only, not the full values. If you need to inspect a value locally, redact API keys, tokens, and passwords before sharing it. opencode debug --help shows which diagnostic commands are available in the installed version; do not guess and run commands that are not listed.

If the error continues, check the latest OpenCode log and storage path. Record the installed version, executable path, full error text, and time of the last run. The official troubleshooting guide lists the Windows logs under %USERPROFILE%\.local\share\opencode\log. Before moving or changing data files or logs, identify the cause and decide how to back them up and restore them. Log and storage locations

In the user’s environment, opencode --mini also ended with Database is not empty and has no session table. Do not use this option as a universal fix for a black screen. Once an error occurs, use the version, executable path, environment-variable names, and diagnostic help output above to distinguish the installation and storage paths before choosing the next step.

The CLI runs but the AI does not respond

Use the error message to distinguish an authentication failure, lack of access to the selected model, or a network error. Check the provider connection. If the same error continues, record when it happened, the version, provider, and error text. Remove API keys and tokens before sharing the record. For further diagnosis, follow the official troubleshooting guide.

An older version runs or you need to update

If you used more than one installation method, check the candidate paths with Get-Command opencode -All. To update the package installed with npm in this guide, run:

cd -LiteralPath $env:USERPROFILE -ErrorAction Stop
npm.cmd install -g opencode-ai@latest

After installation, reopen the terminal and check the version. Do not try to fix a Scoop or Chocolatey installation by layering an npm copy on top of it; first identify which installation method you are using.

Limitations and cautions

When the download page and CLI package instructions change at different times, record the installed package name and version to make problems easier to reproduce. Do not mix commands from different package families.

The exact desktop screens, behavior on ARM PCs, and installation results on PCs with organizational security policies need separate confirmation. If native Windows problems continue, consider the WSL path in the official Windows guide.

Next steps

After confirming the first response, start with small requests to explain a project. Before asking OpenCode to change files, create a recovery point with a Git commit or a copy.

Previous article: Link to be added

Next article: Link to be added

References and sources

• OpenCode Downloads — Windows desktop downloads and the CLI command shown on the page
• Official OpenCode repository — npm package and Windows desktop installer
• OpenCode Intro — Windows installation, provider connection, and project initialization
• OpenCode CLI — interactive use and authentication commands
• OpenCode models — choosing a CLI model and understanding providers and models
• OpenCode on Windows with WSL — WSL setup and Windows file paths
• OpenCode troubleshooting — diagnosing errors
• Node.js downloads — Windows Node.js installers
• npm folder structure — Windows global installation and executable paths