Install OpenCode on Mac & Windows Easily

Installing OpenCode can sometimes feel confusing when setup errors interrupt the process or the tool doesn't run as expected. From missing commands to Node.js compatibility issues, users often struggle during initial installation. This guide on OpenCode installation provides a complete solution to fix common errors and successfully set up OpenCode on Mac and Windows, whether you are using Desktop or CLI/TUI, so you can start coding without delays.

What is OpenCode?

OpenCode is an open-source AI coding agent designed to help developers write, edit, debug, and manage code directly from their preferred environment, whether that's a terminal, IDE, or desktop application. Unlike traditional AI coding assistants that focus mainly on code suggestions, OpenCode can understand an entire codebase, modify files, run commands, and automate development workflows. It also supports multiple AI models and local models, giving developers greater flexibility and control over how they build software.

Prerequisites for installing OpenCode

Before installing OpenCode, make sure your system meets the basic requirements. The exact prerequisites depend on whether you plan to use the desktop application or the terminal-based interface, but having the right setup in place will help ensure a smooth installation process.

For Desktop

Operating System: macOS / Windows / Linux

OpenCode provides desktop applications for major operating systems, allowing developers to install and use the tool in their preferred environment. Ensure your system is using a compatible operating system, such as macOS (Apple Silicon or Intel), Windows (x64), or Linux (.deb, .rpm).

Permission to install apps: You may need administrator or system-level permissions to download and install software on your device. This is especially important in the workplace or managed IT environments where installation rights may be restricted.

Stable internet connection: A smooth internet connection is required to download OpenCode, install updates, and connect to supported AI models and services during setup and usage.

For Terminal/TUI

Terminal access: OpenCode can be installed and used directly from the command line. Ensure you have access to a terminal application, such as Terminal on macOS, Command Prompt or PowerShell on Windows, or a Linux shell.

One install method: OpenCode supports multiple installation methods to accommodate different operating systems and developer preferences. Choose the package manager or installation tool that best matches your environment, such as npm, curl, brew, Scoop, Chocolatey, or WSL.

Basic command-line ability: Familiarity with common terminal commands can make installation and day-to-day usage much easier. While advanced expertise isn't required, understanding basic navigation and command execution is recommended.

How to install OpenCode Desktop?

Installing OpenCode Desktop is a straightforward process that requires only a few simple steps to get the application up and running. Here are the steps to follow.

Step 1: Download OpenCode Desktop

Go to the official OpenCode download page and select the Windows or macOS version of the application. The installer will automatically download to your system. Make sure you are downloading it from the official source for safety and authenticity.

Step 2: Run the installer

Locate the downloaded installer file and double-click it to begin the installation. Follow the on-screen instructions to complete the setup.

Step 3: Complete installation

Proceed through the setup prompts as they appear and select a preferred installation directory when asked. Then allow the installer to complete the setup process on your system.

Step 4: Launch OpenCode Desktop

Once installation is finished, open OpenCode Desktop from the Start Menu or desktop shortcut. Then start a new project or open an existing folder to begin working. Once your workspace is loaded, you can interact with the AI assistant to generate code, debug issues, or build features directly inside your project.

How to Install OpenCode Terminal/TUI on Mac?

OpenCode Terminal (TUI) on Mac can be installed directly using official package managers or a one-line installation command. It is designed for developers who prefer working inside the terminal instead of a graphical interface. Follow these steps to install OpenCode TUI on Mac.

Step 1: Choose an OpenCode Terminal installation method

Visit the official OpenCode download page and navigate to the OpenCode Terminal section. Here, you'll find multiple installation options, including curl, Homebrew, npm, and bun. Select the method that best matches your development environment and copy the corresponding installation command.

Step 2: Open the Terminal application on Mac

Launch the Terminal app on your Mac. You can open it from Applications > Utilities > Terminal or quickly find it using Spotlight Search. This is where you run the OpenCode installation command.

Step 3: Install OpenCode Terminal

Paste the following installation command into the Terminal and press Enter:

Wait for the installation to complete. OpenCode will download the required files and set up the CLI automatically.

Step 4: Launch the OpenCode Terminal Interface

After the installation is complete, run the OpenCode command in Terminal to start the Terminal User Interface (TUI). The interactive interface will open directly in your terminal window, allowing you to connect to an AI provider, configure settings, and begin working with OpenCode.

How to Install OpenCode Terminal/TUI on Windows?

OpenCode supports several installation methods on Windows, including WSL, npm, bun. For the best compatibility and experience, the official documentation recommends using Windows Subsystem for Linux (WSL). The steps below use the WSL installation method. If you already have WSL installed, you can skip the first step.

Step 1: Install WSL (Recommended)

Open PowerShell as Administrator, then run the following command:

This command enables Windows Subsystem for Linux (WSL) and installs Ubuntu by default. Once the installation is complete, restart your computer. The first time you open Ubuntu, Windows will automatically complete the setup of the Linux environment.

Step 2: Open WSL and install OpenCode

Launch your WSL terminal (such as Ubuntu) from the Windows Start menu. If this is your first time opening it, complete the initial setup. Then run the following command to install OpenCode:

Wait for the installation to finish before continuing.

Step 3: Verify the installation

After the installation is complete, run the following command:

If the OpenCode Terminal/TUI launches successfully, the installation is complete, and you can start using OpenCode for AI-assisted coding.

How to integrate external APIs into OpenCode?

One of OpenCode's key advantages is its ability to connect with external AI model providers through API integrations. By adding your own API key, you can access different language models and choose the one that best fits your coding workflow.

Integrate external APIs into OpenCode (General steps)

Below are the steps to integrate external APIs into OpenCode:imi

Step 1: Create an account and generate an API key

Start by creating an account with your preferred AI provider, such as Kimi or another supported service. Once your account is set up, navigate to the provider's API key management page and generate a new API key. Keep this key secure, as it will be required to connect the provider to OpenCode.

Step 2: Open the provider connection menu

Launch OpenCode and open your workspace. In the command interface, run the following command:

This command opens the provider connection menu, where you can add and manage external AI services.

Step 3: Add your API key

Select the provider you want to use from the list of available options. When prompted, paste the API key you generated earlier and confirm the connection. OpenCode will securely store the key and use it to authenticate requests to the selected provider.

Step 4: View available models

After connecting your provider, run the following command to see all models available through that API:

OpenCode will display a list of supported models along with their names and configuration options.

Step 5: Select a model and start using it

Choose the model you want to work with from the available list. Once selected, OpenCode will route your requests through that model, allowing you to generate code, debug applications, and perform other development tasks using the connected API. You can switch models later if your requirements change.

Integrate Kimi APIs into OpenCode

OpenCode supports multiple AI providers, enabling developers to connect external models using API keys for greater flexibility. One of the most powerful options is the Kimi API.

The Kimi API, provided by the Moonshot AI Open Platform, offers access to advanced Kimi language models through an OpenAI-compatible interface. It can be easily integrated into coding tools, applications, and AI-driven workflows using a secure API key. The platform includes a range of Kimi models optimized for coding, reasoning, and long-context understanding tasks.

Follow these steps to integrate Kimi APIs into OpenCode.

Step 1: Create a Moonshot AI account and generate an API key

1. Visit Kimi AI Open Platform and sign in to your account.

2. From the dashboard, navigate to API Keys and click Create API Key.

3. After the key is generated (starts with sk-), copy it immediately and store it securely. The key is only shown once and is used to authenticate requests between OpenCode and Moonshot AI.

Step 2: Connect Moonshot AI to OpenCode

Open your OpenCode workspace and run:

The provider connection menu will appear. Search for Moonshot AI (or Kimi) from the list of built-in providers and select it. OpenCode will prompt you to enter your API key.

When prompted, paste the API key you generated from the Moonshot AI console and press Enter:

Once verified, OpenCode will securely save the credential to ~/.local/share/opencode/auth.json and associate it with your Moonshot AI provider configuration.

Note: OpenCode stores API keys separately from the main configuration file for security. The /connect command handles credential storage, while provider behavior is configured in opencode.json.

Step 3: Configure the provider in opencode.json (if needed)

If you encounter a No endpoints found error after connecting, or if you need to customize the provider setup, add the Moonshot AI configuration to your opencode.json file:

Save the file and restart OpenCode to apply the changes.

Step 4: View available Kimi models

After connecting the provider, run:

OpenCode will display all available models through your Moonshot AI account, including:

Step 5: Select a Kimi model and start coding

Select moonshotai/kimi-k2.6 and set it as the active model. Once selected, OpenCode will use the chosen Kimi model for code generation, debugging, refactoring, and other AI-assisted development tasks.

You can switch to a different model at any time through the same model selection menu.

Tip: If you experience issues with Agent/Tool mode (such as JSON Schema validation errors), this is a known compatibility issue between Moonshot AI's strict schema requirements and OpenCode's tool parameter format. Consider using Chat mode for best stability, or install the opencode-moonshot-compatibility plugin to automatically handle temperature compatibility.

Benefits of using the Kimi API

The Kimi API is designed to support modern development workflows by helping teams move from ideas to implementation more efficiently. Beyond code generation, it can understand different types of inputs, adapt to project requirements, and automate routine engineering tasks. Here are some of its key benefits:

• Turning multimodal inputs into working implementations

Kimi API can interpret information from multiple formats, including design mockups, architecture diagrams, flowcharts, and videos. It uses this context to understand project requirements and convert them into technical specifications or functional code. As a result, teams can move from concept to implementation with fewer manual translation steps.

• Handle long-horizon coding and complex engineering tasks

Kimi API helps OpenCode handle larger coding tasks that require planning, consistency, and refinement. It is useful for building features, refactoring code, and solving complex engineering problems.

• Reason through problems with multi-step tool calls

Kimi API can reason through multi-step tasks and call tools when needed. This helps with debugging, code analysis, and workflows that cannot be completed in a single response.

How to fix issues when installing OpenCode？

Installing OpenCode is usually straightforward, but users may face common setup errors due to environment mismatches, dependencies, or configuration issues. Below is a clear, practical guide to help you resolve the most frequent installation problems quickly and efficiently.

• Command not found: opencode

If you see this error, it means the system cannot locate the OpenCode executable in your PATH. This usually happens when the installation is incomplete or when the environment variables are not set correctly.

To fix it, verify the installation first and ensure the binary directory is added to your system PATH. If installed via npm, check your global npm bin path and update your shell configuration accordingly. Restarting the terminal often resolves the issue after corrections.

• Node.js version too old

OpenCode requires Node.js 18 or higher, and older versions will cause installation or runtime failure.

To resolve this, check your current version using node --version. If it is outdated, upgrade Node.js using a version manager like nvm. After upgrading, reinstall OpenCode to ensure compatibility with the updated runtime environment.

• npm permission errors

Permission errors typically occur when npm tries to install global packages without proper write access.

Instead of using sudo, configure a dedicated npm global directory in your home folder and update PATH settings. This ensures safer and more stable installations. After fixing permissions, rerun the installation command to complete setup successfully.

• Network/firewall issues

In restricted networks or corporate environments, OpenCode installation may fail due to blocked npm registry access or slow downloads.

To fix this, switch to an alternative npm registry or use a direct installation method like curl or binary download. Also, ensure your firewall allows Node.js and npm traffic, as blocked connections often interrupt package installation.

• TUI rendering issues

If OpenCode opens but appears broken, misaligned, or shows garbled text, the issue is usually with terminal compatibility.

Use a modern terminal emulator that supports true color and Unicode rendering, such as Windows Terminal, WezTerm, or iTerm2. Updating your terminal settings or switching environments typically resolves display issues immediately.

Conclusion

Proper OpenCode installation and correct configuration ensure smooth performance across different systems while reducing the risk of common setup errors. When dependencies, terminal settings, and API connections are properly managed, users can quickly resolve issues and maintain a stable development environment. Integrating external services like the Kimi API further enhances flexibility by enabling advanced model access within workflows.