Skip to main content
AI Choice Engine
← All setup guides

OpenCode · Setup guide

How to set up OpenCode

Install the MIT OpenCode terminal client, connect a provider with /connect, review what /init writes, and inspect Plan/Build permissions before a small task. Plan defaults are described differently across current first-party pages; check the installed configuration.

OpenCode

terminal · checked October 2, 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

    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 select Plan and inspect the active edit/bash permissions. Current agent docs say these ask by default, while the README says edits are denied; verify your installed client instead of assuming the label guarantees read-only operation.
  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 restricts tools through configurable permissions. Reject write requests during orientation or explicitly deny edit and state-changing shell access. Build is permissive by default, and --auto approves requests that are not explicitly denied.

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

Client licensing does not establish no storage, retention or training. BYOK follows the selected provider. Go lists 30-day retention for Grok 4.7/4.6 and GPT-6/5.6 Luna, training for Muse Spark 1.3/1.2 Contributor, and a monthly-renewed DeepSeek ZDR agreement valid through October 31, 2026. Zen separately lists 30-day OpenAI/Anthropic retention and free/trial exceptions that log data or allow improvement/training. Check the specific provider/model route: https://opencode.ai/docs/go/ and https://opencode.ai/docs/zen/.

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 days on Grok 4.7/4.6 and GPT-6/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 client is free. BYOK follows provider prices; Zen is pay-as-you-go; Go $10/month and Go Plus $40/month have the same model token rates and different per-model dollar allowances. Paid-model ceilings are 20% in five hours, 50% weekly and 100% monthly; free promotions have their own terms. Menus change, so check /models before committing to a specific model.

Model: usage based

Watch out: If Use balance is enabled, exceeding Go limits falls back to paid Zen credits. Neither Go nor Zen guarantees universal ZDR. Several free/trial Zen routes can log data or use it for improvement, including Contributor and NVIDIA trial endpoints; check the applicable privacy table before private code.

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.

    Configure the local provider using its supported OpenAI-compatible endpoint and an explicit model entry. Verify the actual server URL, tool support, effective context and memory limits; no fixed 16–32K context setting guarantees successful tool use. See https://opencode.ai/docs/providers/.

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 October 2, 2026; use the official source below before installing in a managed or production environment.

OpenCode docsCompare all harnesses