How to Install OpenCode: The Open-Source AI Coding Agent

OpenCode is an open-source AI coding agent that runs in your terminal, as a desktop app, or as an IDE extension. It is provider-agnostic: you point it at whatever LLM you already pay for. This guide covers the full path — install, connect a provider, initialise a project, and verify everything works. Every command below has a copy button.

OpenCode — the open source AI coding agent for the terminal — OpenCode — the open-source AI coding agent

What you will end up with

An opencode command on your PATH that launches a full-screen terminal UI.
At least one LLM provider authenticated, stored at ~/.local/share/opencode/auth.json.
An AGENTS.md in your project root that tells the agent how your codebase is shaped.

Requirements

There is very little to prepare. You need:

A modern terminal emulator — WezTerm or Alacritty (cross-platform), Ghostty (Linux and macOS), or Kitty (Linux and macOS).
An API key for whichever LLM provider you intend to use. If you do not have one yet, OpenCode Zen is a curated option you can sign up for during setup.

Step 1 — Install OpenCode

Pick one of the following. The install script is the recommended route.

Option A — Install script (recommended)

Works on Linux, macOS and WSL2:

bash

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

Option B — Node.js package managers

npm

npm install -g opencode-ai

The same package is available through bun, pnpm and yarn.

Option C — Homebrew (macOS and Linux)

brew

brew install anomalyco/tap/opencode

Use the OpenCode tap rather than brew install opencode. The official formula is maintained by the Homebrew team and updates less often, so you would be running an older build.

Option D — Arch Linux

pacman

sudo pacman -S opencode

For the newest build from the AUR, use paru -S opencode-bin instead.

Option E — Windows

WSL is strongly recommended on Windows: better performance and full feature compatibility. If you prefer a native install, Chocolatey, Scoop, npm and Mise all work.

powershell

choco install opencode

powershell

scoop install opencode

bash

mise use -g github:anomalyco/opencode

Bun-based installation on Windows is still in progress. You can also grab a prebuilt binary from the project releases page.

Option F — Docker

docker

docker run -it --rm ghcr.io/anomalyco/opencode

OpenCode poster showing the terminal based AI coding agent — OpenCode is built terminal-first

Step 2 — Connect an LLM provider

OpenCode speaks to any provider once its key is configured. Launch it, then run the connect command from inside the TUI:

opencode

/connect

Choose OpenCode, sign in at opencode.ai/auth, enter your billing details, copy the API key and paste it back into the terminal when prompted.

You can manage providers entirely from the CLI too. Credentials land in ~/.local/share/opencode/auth.json.

bash

opencode auth login

bash

opencode auth list

bash

opencode auth logout

Step 3 — Initialise a project

Move into the repository you want to work on and start OpenCode with no arguments to get the TUI:

bash

cd /path/to/project

terminal

opencode

Then initialise it for that project:

opencode

/init

This analyses the codebase and writes an AGENTS.md at the project root. Commit it to Git — it is how the agent learns your structure and coding patterns, and it makes every later session more accurate.

Step 4 — Verify the installation

Check that a provider is registered:

bash

opencode auth list

If your provider appears, installation and authentication both succeeded. To see which models that provider exposes, run opencode models.

Everyday commands

OpenCode accepts direct commands, which makes it scriptable and easy to wire into other tools.

bash

opencode run "Explain how closures work in JavaScript"

bash

opencode models

bash

opencode agent list

bash

opencode mcp list

The last one lists your Model Context Protocol servers and whether they connected. OpenCode also supports attaching a terminal to a running backend, which is useful for remote or mobile access:

bash

opencode web --port 4096 --hostname 0.0.0.0

bash

opencode attach http://10.20.30.40:4096

Updating and uninstalling

bash

opencode upgrade

bash

opencode uninstall

Troubleshooting

The opencode command is not found

The install script places the binary in a user-level bin directory. If your shell cannot see it, open a new terminal, or confirm where it landed and add that directory to your PATH.

No models are listed

Authentication did not complete. Re-run opencode auth login and check that ~/.local/share/opencode/auth.json exists afterwards.

Odd behaviour on Windows

Move to WSL. Native Windows support exists but WSL is what the project recommends for full compatibility.

Summary

Install with the script, npm, Homebrew, pacman, Chocolatey, Scoop, Mise or Docker.
Connect a provider with /connect in the TUI or opencode auth login from the CLI.
Initialise with /init to generate AGENTS.md, then commit it.
Verify with opencode auth list and opencode models.