How to Install opencode on Windows, macOS and Linux: Step by Step
Official ways to install opencode on macOS, Linux and Windows, choosing between OpenCode 1 and 2, first launch, and configuring Zukko with the key in an environment variable.
7 min · · opencode · агенты · setup
To install opencode on macOS or Linux, run curl -fsSL https://opencode.ai/v2/install | bash in a terminal. The script installs OpenCode 2, the version recommended by the README and the download page. On Windows, OpenCode 2 has two official paths: install it inside WSL with the same script, or use a zip archive with the binary. Afterwards, check opencode --version, run opencode in your project directory, and connect a provider.
Below are the commands for each OS, upgrade and removal, Zukko setup through opencode.json, and fixes for common launch problems. For an overview of the agent itself, see opencode: what the agent is and how to connect your own models.
Which version to choose
Two branches exist side by side. According to the repository README as of October 29, 2026, they are OpenCode 1 (v1.19.5, released 28.10.2026) and OpenCode 2 (v2.2.1, released 29.10.2026). Both install the opencode command and don't coexist by default, so pick one.
Unless you have a reason to stay on the first branch, install V2. The official repository now lives at github.com/anomalyco/opencode; the old sst/opencode address redirects there.
| Install method | Version |
|---|---|
Script opencode.ai/v2/install | OpenCode 2 |
Script opencode.ai/install | OpenCode 1 |
npm package @opencode/cli | OpenCode 2 |
npm package opencode-ai | OpenCode 1 |
Homebrew: anomalyco/tap/opencode-v2 and opencode | OpenCode 2 |
Arch Linux: pacman -S opencode | OpenCode 2 |
AUR: opencode-bin | OpenCode 1 |
| Windows: Scoop and Chocolatey | OpenCode 1 (1.19.5) |
Installing on macOS and Linux
Install script
curl -fsSL https://opencode.ai/v2/install | bashThe binary goes to $HOME/.opencode/bin. If your shell can't find the command right after installing, see the PATH section below.
Homebrew
The README names a dedicated tap as the recommended option:
brew install anomalyco/tap/opencode-v2The regular brew install opencode formula also installs V2 now.
npm, bun or pnpm
npm install -g @opencode/cli
bun install -g --trust @opencode/cli
pnpm add -g --allow-build=@opencode/cli @opencode/cliThe bun and pnpm commands include the flags from the docs. They allow the package to run its install scripts, so keep them.
Arch Linux
# OpenCode 2, official package
sudo pacman -S opencode
# OpenCode 1, AUR package
paru -S opencode-binIf you need OpenCode 1
Use the same script at the address without /v2, or the opencode-ai npm package:
curl -fsSL https://opencode.ai/install | bash
# or
npm install -g opencode-aiInstalling on Windows
Inside WSL
The Windows documentation as of October 29, 2026 recommends WSL. You install opencode inside the Linux environment with the same curl script and reach Windows drives through paths like /mnt/c/.
# inside WSL
curl -fsSL https://opencode.ai/v2/install | bash
cd /mnt/c/Users/<name>/projects/my-app
opencodeSetting up WSL itself is covered in Claude Code on Windows: native or WSL. After that, the opencode steps match Linux.
Native: OpenCode 2 from a zip archive
Windows package managers are not officially supported for V2. The V2 docs page as of October 29, 2026 offers zip binaries for Windows x64 and ARM64.
Download the archive for your architecture and extract it to a permanent folder inside your user profile. Add that folder to your user PATH and open a new terminal window.
Native: OpenCode 1 via Scoop, Chocolatey or npm
scoop install opencode
choco install opencode
npm install -g opencode-aiPer the V1 docs as of October 29, 2026, Scoop and Chocolatey currently ship version 1.19.5.
Desktop app
Besides the CLI there is OpenCode Desktop for macOS, Windows and Linux, marked BETA in the README. Get it from the download page (checked October 29, 2026), or on macOS with brew install --cask opencode-desktop.
Checking, upgrading and uninstalling
opencode --version # or opencode -v
opencode upgrade # alias: opencode update
opencode uninstall --dry-run
opencode uninstall--version prints the installed version number. Per the V2 CLI reference as of October 29, 2026, uninstall --dry-run lists what would be removed, and session data and config are kept on uninstall.
Moving from V1 to V2
The migration guide as of October 29, 2026 gives three rules:
- if V1 came from a package manager, remove it with that package manager before installing V2;
- the V2 curl installer replaces the V1 binary on its own;
opencode upgrade --majormoves V1 to V2 and removes V1.
First launch
cd ~/projects/my-app
opencodeInside the interface:
/connectpicks a provider and takes your key;/modelspicks a model;/initcreatesAGENTS.mdin the project root.
Connecting Zukko through opencode.json
For opencode, Zukko uses the base URL with the /v1 suffix, the same one OpenAI-compatible clients like Cursor and Codex use: https://api.zukko.pro/v1. The fetch_... key goes in the API key field.
The Zukko docs for opencode connect Claude models through the built-in anthropic provider with an overridden baseURL. Here /v1 is required, even though Claude Code and the Anthropic SDK take the Zukko address without it.
The config lives in ~/.config/opencode/opencode.json for all projects, or in opencode.json at the root of a specific project. To keep the key out of the file, opencode substitutes environment variables written as {env:NAME}, as described in the config docs as of October 29, 2026.
Step 1. Store the key in a variable
macOS, Linux and WSL, line for ~/.zshrc or ~/.bashrc:
export ZUKKO_API_KEY="fetch_..."Windows, PowerShell:
setx ZUKKO_API_KEY "fetch_..."After setx, the value is only visible in new terminal windows.
Step 2. The config
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"baseURL": "https://api.zukko.pro/v1",
"apiKey": "{env:ZUKKO_API_KEY}"
},
"models": {
"claude-opus-5-5": {},
"claude-sonnet-5": {}
}
}
}
}Step 3. Pick a model
Restart opencode and run /models → Anthropic → claude-sonnet-5.
OpenCode 2 has a different official provider format (providers, package, settings.baseURL). It still reads V1-format configs from the same locations and normalizes them in memory without rewriting the file, so the config above works on both branches.
| Model | Input, per 1M tokens | Output, per 1M tokens |
|---|---|---|
| claude-sonnet-5 | $0.4 | $2 |
| claude-opus-5-5 | $0.8 | $4 |
The current catalog with prices is available at GET https://api.zukko.pro/v1/models. A shorter walkthrough is in opencode: connecting to an API gateway in five minutes.
If opencode won't start
command not found and PATH
If the shell can't find opencode, the binary's directory isn't on PATH or the terminal was opened before installation.
which -a opencode
echo $PATH
# for the V2 curl installer, line for ~/.zshrc or ~/.bashrc
export PATH="$HOME/.opencode/bin:$PATH"On Windows, Get-Command opencode in PowerShell does the same check. With npm, global commands live in the directory from npm prefix -g (its bin subdirectory on macOS and Linux).
If which -a shows two copies, you have V1 and V2 installed by different methods. Remove the extra one the same way it was installed.
Permissions
The curl script installs into your home directory and doesn't need sudo. If npm install -g asks for admin rights, use the curl script or move npm's global prefix into your home directory. Installing with sudo npm leaves root-owned files, and later upgrades will need elevated rights too.
On Windows, keep the zip binary folder inside your user profile for the same reason.
Proxy and network
Behind a corporate proxy, curl and npm won't detect it on their own. Set HTTPS_PROXY for curl and npm config set https-proxy for npm; most command-line tools honor that variable.
Check that the gateway is reachable with curl -sS https://api.zukko.pro/v1/models. If the address opens in a browser but not from the terminal, the proxy isn't set in your shell environment.
FAQ
Where can I download opencode from official sources?
The install scripts on opencode.ai, the download page for the desktop app, and the anomalyco/opencode repository (checked October 29, 2026). The npm, Homebrew, Arch, Scoop and Chocolatey packages are listed in the table above.
Can OpenCode 1 and OpenCode 2 be installed side by side?
Not by default, since both install the opencode command. Remove V1 before installing V2, or migrate with opencode upgrade --major.
Do I have to use WSL on Windows?
No. WSL is the documented recommendation, but you can run V2 from the zip archive or install V1 via Scoop, Chocolatey or npm. For a comparison with another terminal agent, see opencode vs Codex CLI.
How much does using opencode through Zukko cost?
You pay only for tokens used, with no subscription fee. For example, 2M input and 0.5M output tokens on claude-sonnet-5: 2 × $0.4 + 0.5 × $2 = $0.8 + $1 = $1.8. The dollar balance can be topped up from $1 via SBP, crypto or a foreign card. You can set daily and monthly spending limits on each key.
What if opencode rejects my key?
Check that ZUKKO_API_KEY is visible in the terminal where opencode runs and that baseURL ends with /v1. Other causes are covered in Invalid API key in opencode. If that doesn't help, contact Zukko support.
zukko
Pay 25×
less
for Claude Code & ChatGPT
One fetch_* key and base URL api.zukko.pro — for Cursor, Claude Code, Codex, and any SDK.
Related articles
- opencode.json Config: Providers, Models and Keys Step by StepA reference for opencode.json: file locations, merge order, key fields, and a step-by-step setup of a custom OpenAI-compatible provider with the API key read from an environment variable.
- Codex on Windows: native and WSL install with a gatewayCodex CLI runs on Windows natively or inside WSL. Installation, where config.toml lives, connecting a Zukko key, and what to do when it fails.
- OpenCode Zen API key or your own provider: what to pick and how to payZen is a ready-made model catalog from the opencode team. A custom provider is your own key and your own endpoint. When to use which, and how to pay from Russia.
- opencode: what this agent is and how to connect your own modelsopencode is an open-source coding agent for the terminal that is not tied to one model vendor. Install, first commands and connecting a key.
- opencode or Claude Code: two terminal agents and how they differBoth read your project, edit files and run commands in the terminal. We compare how they connect to models, where settings live, how agents and MCP work, and what it costs.
- Claude CLI on Linux and macOS: Install and Connect to the GatewayInstall Claude Code on Linux and macOS, put the address and key into your shell profile and verify the connection with curl. PATH and permission errors included.