#Installation & Setup

#Requirements

• Terminal: modern terminal (WezTerm, Alacritty, Ghostty, Kitty recommended)
• Node.js (optional): for npm install -g opencode-ai
• API key: at least one LLM provider, or OpenCode Zen
• Windows: WSL2 recommended; native support via Chocolatey / Scoop / npm

#Install

#Official script (recommended)

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

#npm / Bun / pnpm / Yarn

npm install -g opencode-ai
# or
bun install -g opencode-ai

#Homebrew (macOS / Linux)

brew install anomalyco/tap/opencode

The official tap updates faster; brew install opencode is community-maintained and may lag.

#Windows

# Chocolatey
choco install opencode

# Scoop
scoop install opencode

# npm
npm install -g opencode-ai

#Docker

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

#Verify

opencode --version

#Config Directories

Merge rule: configs from multiple sources are merged, not blindly replaced; on conflict, later sources win. See Architecture for full order.

#Connect a Provider

In the TUI:

/connect

Follow prompts, for example:

#OpenCode Zen (good for beginners)

1. Choose opencode
2. Open opencode.ai/auth in the browser
3. Sign in and paste the API key into the terminal

#Other providers

Anthropic, OpenAI, Google, local Ollama, etc. (see /connect list). You can also configure manually in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-6"
}

Model IDs use provider/model-id. Run opencode models to list available models.

#Global Config Example

~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/gpt-5.1-codex",
  "autoupdate": true,
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

#Common Environment Variables

#Troubleshooting

Issues on Windows?
Install Node and OpenCode inside WSL2 and work on the Linux filesystem.

No models listed?
Run opencode models; ensure Provider is connected via /connect and API key is valid.

Config ignored?
Check project opencode.json overrides; validate JSON against the schema.

#Next Steps

• Quick Start: enter TUI and run /init
• Config & CLI Reference: full options