OpenCode setup and first-use guide

Checked against the official docs on 2026-10-20. This guide is compiled from OpenCode's documentation; FollowAgents has not yet run an install test on a current OpenCode release. OpenCode changes quickly, so the linked official pages win wherever they differ.

OpenCode is an open source terminal coding agent whose main draw is that it is not tied to one model vendor: it works with OpenAI, Anthropic, Gemini, GitHub Copilot or a local Ollama. Three things trip up a first run: which version you installed, where the model comes from and who pays for it, and whether it edits files and runs commands without asking. This guide takes them in that order.

Still comparing tools? See OpenCode's features, fit and source review, OpenCode vs Claude Code or OpenCode vs Kilo Code.

First: OpenCode 1 or OpenCode 2?

OpenCode is in the middle of a move from 1.x to 2:

The docs warn that the two installs can conflict, so pick one. Commands below follow OpenCode 1, which has the fuller documentation; on 2 they are mostly the same, but the OpenCode 2 docs are authoritative there. Sources: official docs and GitHub Releases.

Step 1: Install

On macOS or Linux, use the official script:

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

npm and Homebrew work too (the docs recommend OpenCode's own tap; the official formula updates less often):

npm install -g opencode-ai
brew install anomalyco/tap/opencode

The npm package is opencode-ai — don't install look-alikes. Confirm with opencode --version. Commands are from the official install docs.

Step 2: Connect a model

OpenCode itself is free; the cost is the model you connect. Run opencode in a project, type /connect, pick a provider, then sign in through the browser or paste an API key. Credentials are stored in ~/.local/share/opencode/auth.json — never commit it. opencode auth list shows what is configured.

Common setups (see the official providers docs):

About Claude Pro / Max: the docs say third-party plugins can route a Claude Pro/Max subscription through OpenCode, but Anthropic explicitly prohibits this, and OpenCode removed its bundled plugins as of 1.3.0. To use Claude models in OpenCode, use an Anthropic API key.

A local Ollama config from the docs (swap in a model you have pulled):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "llama2": { "name": "Llama 2" } }
    }
  }
}

If tool calls fail with a local model, the docs suggest raising Ollama's num_ctx to around 16k–32k.

Step 3: Your first task and its permissions (read this)

Unlike Codex or Claude Code, OpenCode edits files and runs commands without asking by default. Per the official permissions docs, most permissions default to allow; only paths outside the project (external_directory) and suspected loops (doom_loop) ask first, and .env files are denied for reading.

For a first run:

1. Start opencode in a Git project with a clean commit, so anything can be rolled back.
2. Press Tab to switch to the Plan agent before asking. Per the official agents docs, Plan asks before every file edit and bash command; the default Build agent has every tool enabled.
3. To make Build ask too, put this in opencode.json at the project root:

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

The last matching rule wins, so the "*" catch-all goes first. Each prompt lets you allow once, allow for the session, or reject.

Step 4: Teach it your project with AGENTS.md

Run /init and OpenCode analyses the project and writes AGENTS.md at the root — structure, build and test commands, conventions. The docs recommend committing it so the team shares it. Add your own rules afterwards, such as "run the tests after editing" or "never touch migrations/". See the official docs.

On Windows

The docs recommend running OpenCode inside WSL for file-system performance, full terminal support and tool compatibility. Install WSL with Microsoft's guide, then run the Step 1 script in the WSL terminal. Your C: drive is /mnt/c/ there; for speed, clone the project into the WSL file system (such as ~/code/) instead.

Without WSL, choco install opencode, scoop install opencode or npm also work. See the official Windows (WSL) docs.

FAQ

Is OpenCode free? The software is free and open source (MIT, source at anomalyco/opencode). The models cost money: a ChatGPT or Copilot plan, a vendor API key, or OpenCode's pay-per-request service. Fully free options are local models or the limited-time Free models.

Does OpenCode upload my code? The site says OpenCode itself does not store your code or context data, but your code is sent to whichever model provider you connect, under that provider's data policy.

Can I use my Claude subscription? Not recommended: the docs state Anthropic explicitly prohibits using Claude Pro/Max through OpenCode plugins. Use an Anthropic API key instead.

OpenCode or Claude Code? Mostly a question of whether you want to switch models and whether open source matters to you. See OpenCode vs Claude Code, or the AI coding agents ranking.