Installing opencode: a basic guide

Goal

By the end you'll have opencode installed, a model provider connected, and a first session running against a real project, with an AGENTS.md file generated for that repo.

opencode is an open-source, terminal-based coding agent. It's provider-agnostic: you bring your own API key (Anthropic, OpenAI, OpenRouter, local models, or the hosted opencode Zen gateway) instead of being tied to one vendor. It runs as a TUI, a non-interactive command, or a headless server.

Prerequisites

macOS, Linux, or Windows.
A modern terminal emulator. GPU-accelerated terminals (WezTerm, Alacritty, Ghostty, Kitty) render the TUI best.
An API key for at least one LLM provider, or an opencode Zen account.
A local project to work on.

This guide covers opencode as of September 2026.

Steps

1. Install the binary

Pick the method for your system.

macOS / Linux / WSL (script):

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

Homebrew:

brew install anomalyco/tap/opencode

npm (or bun / pnpm / yarn):

npm install -g opencode-ai

Arch Linux:

paru -S opencode-bin

Windows (Scoop or Chocolatey):

scoop install opencode
# or
choco install opencode

The install script drops the binary in ~/.local/bin. If that directory isn't on your PATH, add it:

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
source ~/.bashrc

2. Verify the install

opencode --version

Expected check: it prints a version number. If the shell says "command not found", open a new terminal so it picks up the updated PATH.

3. Connect a provider

Launch opencode and run the connect command:

opencode

Inside the TUI:

/connect

Pick your provider. For a first run, opencode Zen is the simplest: it's a hosted gateway that works with a single key from opencode.ai/auth. Paste the key when prompted.

To manage credentials from outside the TUI:

opencode auth login    # add a provider key
opencode auth list     # see connected providers

Keys are stored in ~/.local/share/opencode/auth.json.

4. Start a session on your project

cd path/to/your/project
opencode

Run /init once. opencode scans the repo and writes an AGENTS.md file with project context that it reads on every future session. Commit that file.

Reference specific files in your prompts with @:

Explain what @src/server.ts does and add error handling

5. Use it without the TUI

For quick questions or scripting, skip the interface:

opencode run "Explain the difference between async and defer on script tags"

6. Keep it updated

opencode upgrade

If you installed via npm or a package manager, update through their own channels instead.

Expected result

opencode --version prints a version.
opencode auth list shows at least one connected provider.
opencode opens the TUI on your project and /init has generated AGENTS.md.
opencode run "..." answers from the terminal without opening the TUI.

Troubleshooting

Common issues

opencode: command not found after installing: the binary landed in ~/.local/bin but it's not on your PATH. Add it and reload your shell profile, or open a new terminal.
The TUI renders with broken characters or colors: your terminal doesn't support the required features. Switch to WezTerm, Alacritty, Ghostty, or Kitty.
No providers configured / model errors: run /connect in the TUI or opencode auth login, and confirm the key with opencode auth list.
Wrong model being used: run opencode models to list what's available per provider, then pick one with /models in the TUI.
Undo a change opencode made: run /undo in the session.

Next step

Tune opencode per project by editing opencode.json at the repo root (models, permissions, MCP servers), and share a session transcript with /share.