Part of the AI Coding Harness Guide — environment design for coding agents in production.

How to Install OpenCode: npm, curl, Homebrew, Windows, Desktop App and API Key#

Published by

Run curl -fsSL https://opencode.ai/v2/install | bash on macOS, Linux or WSL, or npm install -g @opencode/cli on any system with npm, including Windows. Both install OpenCode 2 as the opencode command (v2.3.0, published 2026-11-13). Then run opencode, type /connect, pick a provider and paste its API key.[1]

What is OpenCode?#

OpenCode is an open source (MIT) AI coding agent that runs as a terminal UI, a desktop app or a web UI, and works with the model provider you connect: Anthropic, OpenAI, Amazon Bedrock, Google Vertex, Azure, or the OpenCode Console's own pay-as-you-go models.[1][4] Two lines ship in parallel. OpenCode 2 is a rewrite published on npm as @opencode/cli since 2.0.0 (2026-09-11), and it is what opencode.ai/docs and the default install script now give you. OpenCode 1 keeps shipping as the npm package opencode-ai (1.19.5, published 2026-10-28), documented at opencode.ai/v1/docs.[2][5] Both install a command named opencode, so pick one: OpenCode 2 for a new install, 1.x if you depend on 1.x plugins or language servers (LSP), which OpenCode 2 does not run.[5]

Install commands for each system#

SystemOpenCode 2 (@opencode/cli)OpenCode 1 (opencode-ai)
macOS, Linux, WSL (script)curl -fsSL https://opencode.ai/v2/install | bashcurl -fsSL https://opencode.ai/install | bash
Any system with npmnpm install -g @opencode/clinpm install -g opencode-ai
Bunbun install -g --trust @opencode/clibun install -g opencode-ai
pnpmpnpm add -g --allow-build=@opencode/cli @opencode/clipnpm install -g opencode-ai
Yarnyarn global add @opencode/cliyarn global add opencode-ai
Homebrew (macOS, Linux)brew install anomalyco/tap/opencode-v2brew install anomalyco/tap/opencode (1.x docs)
Arch Linuxparu -S opencode-beta (AUR)paru -S opencode-bin (AUR)
misemise use -g opencode (mise 2026.10.9+)mise use -g github:anomalyco/opencode
Windowsnpm install -g @opencode/cli, or the standalone zipnpm install -g opencode-ai, choco install opencode, scoop install opencode
Dockerghcr.io/anomalyco/opencode:<version>docker run -it --rm ghcr.io/anomalyco/opencode

The commands come from the official docs of each line.[1][2] The README also lists brew install opencode (the Homebrew core formula, "updated less" than the tap), sudo pacman -S opencode for Arch's stable package, and nix run github:anomalyco/opencode.[7] Check the result with opencode --version in a new terminal.

Install on macOS and Linux#

The install script is the shortest path:

curl -fsSL https://opencode.ai/v2/install | bash

It detects your OS and CPU, picks a baseline build on x64 CPUs without AVX2 and a musl build on musl systems such as Alpine, downloads the matching package from npm, and installs it to ~/.opencode/bin. It then adds that folder to PATH in your shell's config file (.zshrc, .bashrc, config.fish and similar), creating ~/.zshrc on a new Mac. Options: --version <version> installs a specific release, --binary <path> installs a local file, and --no-modify-path leaves your shell config alone.[6]

curl -fsSL https://opencode.ai/v2/install | bash -s -- --version 2.3.0

With Homebrew, use the tap the docs recommend, because it is always up to date:[1][7]

brew install anomalyco/tap/opencode-v2

Prebuilt standalone executables exist for macOS (Apple silicon, Intel, Intel baseline) and for Linux glibc and musl (ARM64, x64, x64 baseline), linked from the install page and attached to each GitHub release.[1][12]

Install with npm: npm install -g @opencode/cli#

npm install -g @opencode/cli

The npm package is a thin wrapper: a postinstall script picks the native opencode executable for your platform. Bun and pnpm block postinstall scripts by default, which is why their commands carry --trust and --allow-build=@opencode/cli. Vite+ (vp install -g @opencode/cli) needs no flag.[1]

The package name decides the line. opencode-ai is OpenCode 1 only; OpenCode 2 ships as @opencode/cli.[11] If you ran npm install -g opencode-ai from an older tutorial, you have 1.x.

Install OpenCode on Windows#

OpenCode 2 runs natively on Windows, x64 and ARM64. Its docs say Windows package managers are not supported; use npm or a standalone zip:[1]

npm install -g @opencode/cli
  • Standalone zip: opencode-windows-x64.zip, opencode-windows-arm64.zip, or opencode-windows-x64-baseline.zip for CPUs without AVX2, from the install page or the GitHub release.
  • Git Bash or MSYS2: the curl script detects Windows and installs opencode.exe, choosing the ARM64 build on ARM64 Windows.[6]
  • WSL: WSL is Linux, so the macOS and Linux commands above apply inside it. The 1.x docs recommend WSL "for the best experience on Windows": run OpenCode in the WSL terminal and reach Windows files under /mnt/c/.[9]

Chocolatey and Scoop are 1.x-era paths. The 1.x docs list choco install opencode and scoop install opencode. On 2026-11-15, the Chocolatey opencode package is at 1.19.5, and Scoop's main bucket opencode is at 2.3.0, with versions/opencode1 for 1.x. Both are maintained outside the OpenCode docs.[2]

OpenCode desktop app#

OpenCode Desktop (beta) is a separate download from opencode.ai/download:[1][7]

SystemDownload
macOSopencode-desktop-mac-arm64.dmg (Apple silicon), opencode-desktop-mac-x64.dmg (Intel)
Windowsopencode-desktop-win-x64.exe, opencode-desktop-win-arm64.exe
Linux.deb, .rpm or .AppImage, x64 and ARM64

On macOS it is also a Homebrew cask:

brew install --cask opencode-desktop

The same files are attached to each GitHub release, for example v2.3.0.[12] For the browser UI instead, OpenCode 2 uses opencode pair, which prints a one-time link that expires in 5 minutes.[1]

Set your provider API key ("opencode key")#

Start OpenCode in a project and connect a provider from the TUI:

opencode
/connect
/models

/connect lists the providers, asks for an authentication method when there is more than one (API key, OAuth, or a provider command), and saves the result as an account. Run it again to add another account.[4] The same flow works without the TUI:

opencode auth login                          # interactive provider picker
opencode auth login anthropic --method key   # skip straight to API-key entry
opencode auth list
opencode auth switch anthropic work          # switch the active account
opencode auth logout anthropic work

API-key entry needs an interactive terminal. To use an environment variable instead, OpenCode 2 reads it from the background server, so set it there. This stops the running service, and the next opencode command starts it with the new value:[4]

opencode service set env ANTHROPIC_API_KEY sk-ant-...

ANTHROPIC_API_KEY=sk-ant-... opencode --standalone works for one private session. A saved account wins over an environment variable for the same provider. OpenCode 2 stores keys and OAuth tokens in its SQLite database, usually ~/.local/share/opencode/opencode.db (opencode debug paths db prints it), and imports the 1.x auth.json on first start. In 1.x, opencode auth login writes to ~/.local/share/opencode/auth.json.[4][8]

For the OpenCode Console's own models (opencode.ai/zen now redirects there), sign in at opencode.ai/console, add billing and credits, copy the API key, then run /connect, choose the OpenCode pay-as-you-go provider and paste it.[13]

Update OpenCode#

opencode upgrade                      # alias: opencode update
opencode upgrade 2.0.21 --method bun  # a specific version, with the package manager you used

opencode upgrade updates to the latest release of your line.[3] On 1.x it stays on 1.x since v1.19.2, and opencode upgrade --major moves you to OpenCode 2 and removes OpenCode 1. --method takes curl, npm, pnpm, bun or brew.[8] The 1.x install script refuses a 2.x version and prints the 2.x install command instead.[11]

OpenCode 1 and 2 use the same config locations, and the two are not installed side by side by default. Remove a package-managed 1.x install before installing 2; the 2.x curl script replaces a 1.x executable in place.[5] Plugins written for 1.x do not run in OpenCode 2.

Uninstall OpenCode#

Preview, then remove:

opencode uninstall --dry-run
opencode uninstall

In OpenCode 2, uninstall stops the background service and persistent terminals, deletes the global cache, and removes the program through the package manager that installed it. A curl install prints the last command to delete the executable yourself. Sessions, config and state are kept; --force (-f) skips the prompt.[3][10]

In 1.x, opencode uninstall removes the related files too, unless you pass --keep-config (-c) or --keep-data (-d).[8] Remove OpenCode Desktop with your OS's app manager.

Common install errors#

SymptomCauseFix
opencode: command not found after the curl script~/.opencode/bin is not on PATH in this shellOpen a new terminal, or run export PATH=$HOME/.opencode/bin:$PATH. The script prints this line when it cannot write your shell config.[6]
Error: 'tar' is required but not installed.The script unpacks a .tgzInstall tar, then rerun.[6]
Error: Version X is not available for <target>Pinned --version has no build for your platformPick a version from the npm page the error links to.[6]
Error: OpenCode 2.3.0 is not an OpenCode 1 release, so this installer can't install it.2.x requested through opencode.ai/install (the 1.x script)Use curl -fsSL https://opencode.ai/v2/install | bash, or opencode upgrade --major from 1.x.[11]
opencode --version shows 1.x after installing 2A package-managed 1.x install is still on PATH, or you installed opencode-aiUninstall the 1.x package, then reinstall @opencode/cli.[5]
Bun or pnpm install leaves no working opencodeThe postinstall script that picks the executable was blockedUse bun install -g --trust or pnpm add -g --allow-build=@opencode/cli.[1]
mise use -g opencode installs 1.xmise older than 2026.10.9Update mise.[1]
OpenCode starts but hangs or cannot reach its serverThe shared background service is stuckopencode service status, then opencode service restart. Logs: ~/.local/share/opencode/log/opencode.log.[10]

The README also says to remove versions older than 0.1.x before installing.[7]


FAQ#

Q: What is OpenCode?

A: An open source (MIT) AI coding agent with a terminal UI, a desktop app and a web UI. It works with the model provider you connect. OpenCode 2 (@opencode/cli) is the current line; OpenCode 1 (opencode-ai) still gets releases.

Q: How do I install OpenCode with npm?

A: npm install -g @opencode/cli installs OpenCode 2. npm install -g opencode-ai installs OpenCode 1. Both put an opencode command on your PATH.

Q: How do I install OpenCode on Windows?

A: Run npm install -g @opencode/cli, or download opencode-windows-x64.zip (or the ARM64 zip) from opencode.ai/docs. You can also install the Linux build inside WSL with curl -fsSL https://opencode.ai/v2/install | bash. The OpenCode 2 docs do not support Windows package managers.

Q: Is there an OpenCode desktop app?

A: Yes, in beta, for macOS (.dmg), Windows (.exe, x64 and ARM64) and Linux (.deb, .rpm, .AppImage), from opencode.ai/download. On macOS, brew install --cask opencode-desktop also works.

Q: How do I add an API key to OpenCode?

A: Run /connect in the TUI, pick the provider and paste the key, or run opencode auth login anthropic --method key in a shell. opencode auth list shows saved accounts.

Q: How do I update OpenCode?

A: Run opencode upgrade (or opencode update). On 1.x, opencode upgrade --major moves you to OpenCode 2.

Q: How do I uninstall OpenCode?

A: Run opencode uninstall --dry-run to preview, then opencode uninstall. OpenCode 2 keeps your sessions and config; 1.x removes them unless you pass --keep-config or --keep-data.

Q: Is OpenCode free?

A: The program is free and open source; you pay your model provider. The OpenCode Console sells pay-as-you-go credits and OpenCode Go subscriptions at $10, $40 (Go Plus) and $20 per member (Go Teams) a month.


Sources: [1] OpenCode docs: Intro | [2] OpenCode 1 docs: Intro | [3] CLI commands | [4] CLI providers | [5] Migrate from V1 | [6] Install script, v2.3.0 | [7] README, v2.3.0 | [8] OpenCode 1 CLI | [9] OpenCode 1: Windows (WSL) | [10] Troubleshooting | [11] OpenCode 1 install script | [12] Release v2.3.0 | [13] Console models

Related: OpenCode 2 Version Tracker | OpenCode Version Tracker (1.x) | OpenCode config reference | OpenCode v1.19.2: the 1.x / 2.x update split | How to Install and Update Claude Code

Get the weekly digest

New Claude Code, Codex, Gemini CLI and OpenCode guides and release analyses, once a week, plus occasional notes.

One email a week plus occasional notes. Confirm by email; unsubscribe from any issue. Privacy