OpenCode: installing and configuring

By Ivo Donker · October 28, 2026 — created with AI assistance (writer: DeepSeek V4.1 Flash; critic: Gemini 3.8 Flash)

OpenCode: ReviewInstall & set upNewsTechnical tutorial

As of September 2026, compiled from our own notes and news archive; text machine-generated and editorially checked. Check versions and commands in the official documentation.

In this guide you install OpenCode, an open-source coding agent for the terminal, on macOS, Linux or Windows. You connect a model provider, let OpenCode get to know your project and set up the first safety settings. Everything comes from the official documentation (as of September 2026).

What you need

• A terminal on macOS, Linux or Windows.
• Access to at least one language model: an API key from a provider (for example Anthropic, OpenAI or Google), OpenCode's own service Zen, or a local model via Ollama or LM Studio.

OpenCode is also available as a desktop app and as an extension for your editor; this guide is about the terminal version.

Install

The quickest way, on macOS and Linux:

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

Or choose what suits your system:

npm install -g opencode-ai                 # met Node.js
brew install anomalyco/tap/opencode        # Homebrew (macOS/Linux)

On Windows:

choco install opencode     # Chocolatey
scoop install opencode     # Scoop

Or without installing anything, via Docker:

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

Then check:

opencode --version

Connecting a model provider

Start OpenCode and type:

/connect

Choose your provider and paste your API key. OpenCode stores the keys in ~/.local/share/opencode/auth.json, outside your projects, so they do not end up in git. The same can be done from the command line:

opencode auth login     # provider toevoegen
opencode auth list      # zien wat er gekoppeld is

If you do not yet have a key, OpenCode recommends its own service Zen: log in at opencode.ai/auth, enter payment details, copy the key and paste it into /connect.

If you want to work locally with Ollama, see the tutorial: it explains how to add your own or a local provider.

Letting OpenCode get to know your project

Go to your project directory and start OpenCode:

cd ~/mijn-project
opencode

Then type:

/init

OpenCode examines your project and creates an AGENTS.md with the structure, commands and conventions. Commit that file so that OpenCode (and other coding agents) use it in every session.

Plan or Build

Use Tab to switch between the two main agents:

• Plan: analyses and suggests, but does not change code. Start with this when you are getting to know an unfamiliar codebase.
• Build: has all the tools and makes changes.

With @ you refer to a file in your prompt, for example @src/auth.ts.

Initial safety settings

By default, OpenCode may perform most actions without asking; it does not read .env files by default. For a cautious start, put an opencode.json in the root of your project:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status": "allow",
      "npm test": "allow"
    }
  }
}

OpenCode will then first ask for permission for every edit and every shell command, except the two you allow. You can always make it more permissive later.

Checking that it works

A one-off command without an interactive session:

opencode run "Leg in drie zinnen uit wat dit project doet."

If you get a sensible answer, the installation and provider are working.

Updating

opencode upgrade

A specific version is also possible: opencode upgrade v1.2.3. If you installed via Homebrew, npm, Chocolatey or Scoop, you can also update with that program. With the autoupdate key in your configuration you determine whether OpenCode updates itself (true), only reports that an update is available ("notify"), or does nothing (false).