Skip to main content
AI Choice EngineAI Choice Engine
Browse decision tools
← All setup guides

OpenCode · Setup guide

How to set up OpenCode

Install the open-source OpenCode terminal agent, connect a model provider with /connect, initialise a project with /init, and start in Plan mode before allowing Build-mode edits.

OpenCode

terminal · checked August 9, 2026

~12 minIntermediate
Start installOpen OpenCodeCompare itBuyer guide

The “Open OpenCode” link goes to the vendor site. It is not an affiliate-tracked link on this page — no commission is claimed for that click. Affiliate disclosure.

Critical: finish install before closing the window

Keep the installer terminal open until you see a success message. If you used an admin window, do not close it until verification works. Then open a new Terminal or PowerShell window and run the verify step — PATH updates rarely apply to shells that were already open, especially on Windows.

Before you begin

  • macOS, Linux, or Windows (WSL2 recommended on Windows).
  • A modern terminal app.
  • An API key or OpenCode Zen account for at least one model provider.
  • A git project folder you can safely explore.

Authentication

/connect inside the TUI (OpenCode Zen or any supported provider)

Account: Provider API key or OpenCode Zen billing

OpenCode does not replace provider billing — you pay the model host you connect.

Install or open it

1. Get the harness ready

These steps are written for beginners. On Mac, Terminal is the black/white text window where you type commands. On Windows, use PowerShell or Terminal. Use the OS tabs to hide steps that are not for your computer, then copy one command at a time.

  1. 01

    Open Terminal on a Mac

    Mac

    Click the Spotlight search icon (magnifying glass) at the top-right of the menu bar, or press Command (⌘) + Space. Type Terminal and press Return. A text window opens — that is where you paste the install commands below. Leave it open.

  2. 02

    Open Terminal or PowerShell on Windows

    Windows

    Press the Windows key, type Terminal or PowerShell, then press Enter. Use that window for the commands below. If Windows asks for permission to run a script or install software, read the prompt before approving.

  3. 03

    How to paste a command

    Copy one command at a time from this page. Click inside the terminal window, paste (Mac: ⌘+V, Windows: Ctrl+V or right-click → Paste), then press Return / Enter. Wait until the prompt comes back before running the next command. You do not need to type the leading $ if you see one in other docs.

  4. 04

    Do not close the installer until verified

    Keep the installer terminal (or admin PowerShell) open until the install finishes without errors. Closing early can leave a half-written binary or an incomplete PATH update — especially on Windows.

  5. 05

    Open a new terminal after installers

    PATH updates often only apply to new shells — especially on Windows. Do not close the install session until the installer finishes, then open a fresh Terminal/PowerShell before running --version checks.

  6. 06

    Inspect before you pipe an installer

    Commands like curl … | bash download and run a script immediately. Prefer the official package manager when offered. If you use a curl installer, you can download the script first, open it in a text editor, then run it — never paste installers from random blogs.

  7. 07

    Install OpenCode on Mac / Linux

    Mac

    Paste the official installer. Prefer this or Homebrew over random mirrors. When it finishes, open a new Terminal window.

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

    You should see: The installer finishes without an error. Open a new terminal before the verify step so PATH updates apply.

    If this fails
    • The install command errors, or the next verify step says “command not found”. Re-run the official install command with network access, then open a brand-new terminal window before verifying.
    OpenCode docs
  8. 08

    Optional: Homebrew on Mac

    Mac

    The anomalyco tap stays closer to upstream releases than the slower official brew formula.

    bash
    brew install anomalyco/tap/opencode

    You should see: The installer finishes without an error. Open a new terminal before the verify step so PATH updates apply.

    If this fails
    • The install command errors, or the next verify step says “command not found”. Re-run the official install command with network access, then open a brand-new terminal window before verifying.
    OpenCode GitHub
  9. 09

    Windows: WSL2 first; native installers do not require Scoop

    Windows

    For beginners, install OpenCode inside WSL2 and use the curl path. Native Windows does not require Scoop: Chocolatey (`choco install opencode`), npm (`npm install -g opencode-ai`), Mise (`mise use -g github:anomalyco/opencode`), or a binary from GitHub Releases all work. Scoop is optional if you already use it.

    powershell
    npm install -g opencode-ai

    You should see: The installer finishes without an error. Open a new terminal before the verify step so PATH updates apply.

    If this fails
    • The install command errors, or the next verify step says “command not found”. Re-run the official install command with network access, then open a brand-new terminal window before verifying.
    OpenCode docs
  10. 10

    Verify the install

    If the command is missing, open a new terminal. On npm installs, use the official registry if postinstall fails to fetch platform packages.

    bash
    opencode --version

    You should see: A version string. Open a new terminal if missing; confirm ~/.opencode/bin or ~/bin is on PATH.

    If this fails
    • opencode: command not found. Open a new terminal. Confirm the install path (often ~/.opencode/bin or ~/bin) is on PATH, or re-run the official installer.

Repository or project

2. Start in the right place

Keep the first repository small, clean, and easy to roll back while you learn the harness’s permissions and context model.

  1. 01

    Enter your project

    cd into the repository root in Terminal.

    bash
    cd path/to/your-repository

    You should see: The prompt shows you are inside the intended folder (check with `pwd`).

    If this fails
    • “No such file or directory” or you are still in your home folder. Create or clone the practice folder first, then `cd` into it before starting the tool.
  2. 02

    Start OpenCode

    Run opencode to open the terminal UI.

    bash
    opencode

    You should see: The tool starts in this folder and waits for your first prompt (or shows a short first-run / sign-in screen).

    If this fails
    • Nothing happens, or you land in the wrong folder. Confirm you are inside the practice repo (`pwd`), that you signed in, and that you opened a new terminal after install.
    OpenCode intro
  3. 03

    Connect a provider

    Inside OpenCode, type /connect and follow the prompts. Beginners can pick OpenCode Zen, create an account at opencode.ai/auth, then paste the API key when asked.

    bash
    /connect

    You should see: The command finishes without an error before you continue.

    If this fails
    • The command exits with an error. Read the last few lines of output, fix the named issue, then re-run this step before continuing.
  4. 04

    Initialise the project

    Still inside OpenCode, run /init so it can study the repo and write an AGENTS.md helper file. Review that file before trusting later edits.

    bash
    /init

    You should see: The command finishes without an error before you continue.

    If this fails
    • The command exits with an error. Read the last few lines of output, fix the named issue, then re-run this step before continuing.

First run

Plan mode before Build mode

Use this task to test the workflow before handing over a larger repository or production responsibility.

  1. 01Press Tab to enter Plan mode (lower-right indicator).
  2. 02Ask OpenCode to explain how one feature works and propose a tiny improvement — without editing yet.
  3. 03Only after you like the plan, Tab back to Build mode and approve a narrow change.

Why this is safe: Plan mode disables edits so beginners can learn the UI without accidental rewrites.

Stop and review if

  • OpenCode wants to edit before you leave Plan mode.
  • AGENTS.md or the plan references secrets you did not intend to share.
  • You cannot undo with /undo after a bad Build attempt.

The operating boundary

Privacy, data, and cost

The setup is incomplete until you know what the harness can see, what account pays for it, and who approves a risky action.

Privacy

OpenCode itself does not store your code by default. BYOK follows your provider. OpenCode Go is not blanket ZDR: Grok 4.5 and GPT-5.6 Luna retain about 30 days; DeepSeek V4 Flash ZDR only through 2026-08-31. OpenCode Zen claims ZDR/no training for many paid models, but free/trial Zen models may use data to improve — avoid confidential code on those endpoints.

Training on code: tier dependent

Depends on the connected provider and whether you use OpenCode Zen or Go — retention differs by model (for example ~30-day retain on Grok 4.5 / GPT-5.6 Luna via Go).

Sensitive repos: Practice on a non-sensitive clone first; do not connect production credential stores on day one.

Pricing

The OpenCode client is free. BYOK follows provider pricing; Zen is curated pay-as-you-go, while Go is a separate subscription. Zen free/trial models can have different data handling from paid/ZDR models.

Model: usage based

Watch out: Long agent sessions and large /init context can burn tokens quickly. Avoid free/trial Zen models for confidential repositories because they may use data to improve. Do not treat OpenCode Go as universal ZDR.

Estimate a seat stack

When setup goes wrong

  • opencode: command not found.

    Open a new terminal. Confirm the install path (often ~/.opencode/bin or ~/bin) is on PATH, or re-run the official installer.

  • npm install fails looking for an opencode-darwin-* package.

    Retry with npm install -g opencode-ai@latest --registry=https://registry.npmjs.org or switch to the curl / Homebrew path.

  • /connect succeeds but prompts fail.

    Confirm billing on the provider, re-run /connect, and try a known-good model from OpenCode’s verified list.

  • Local Ollama tools never fire or context feels truncated.

    Raise Ollama num_ctx (agents usually need 16–32k+, not the ~4k default). OpenCode expects an OpenAI-compatible /v1 door at Ollama (http://127.0.0.1:11434/v1) or LM Studio (http://127.0.0.1:1234/v1) — do not point it at an Anthropic Messages URL meant for Claude Code.

Next steps

After the first successful run

Keep the pilot small, then compare surfaces and budget before a team rollout.

Compare harnessesBuyer guideLocal LLM coding setupOpen-source agents hubAI stack cost calculatorGPU inference (rent)Local GPU sizingBuyer guidesLocal open-source AI guide

Setup details change quickly. The page was checked August 9, 2026; use the official source below before installing in a managed or production environment.

OpenCode docsCompare all harnesses