What Is OpenCode? Setup and Where Your API Keys Live

OpenCode is an open source AI coding agent. Its docs say it's "available as a terminal-based interface, desktop app, or IDE extension." You install it with one command, connect a model provider, and it reads and edits code in your project. Any API key you add with /connect is saved in ~/.local/share/opencode/auth.json, outside your project folder.

By Gary, Greenlight My App · Updated Oct 31, 2026 · How we checked this: Tested on Oct 31, 2026, about 6:55–6:58 AM ET, on a Linux test machine with an empty home folder. We installed OpenCode 1.19.5 with the official install script, added a fake OpenAI key, checked where and how it was stored, set up a project config and .gitignore, and uninstalled it. We did not connect a real model, so we didn't test answers or code edits. We also read OpenCode's docs (last updated Oct 30, 2026) and the Claude Code setup docs. Drafted with AI tools and reviewed by a person before publishing.

Most OpenCode guides stop after the install. This one also shows where your keys end up, because a coding agent works inside your project folder, and that folder usually ends up in Git.

What is OpenCode?

OpenCode's docs describe it in one line: "OpenCode is an open source AI coding agent. It's available as a terminal-based interface, desktop app, or IDE extension." The download page FAQ says the source code "is public on GitHub under the MIT License," and Socket's Oct 29, 2026 report names its developer as Anomaly. The OpenCode GitHub repo is anomalyco/opencode (external). When people search "OpenCode AI," this is the tool they mean.

In practice, OpenCode is a chat that can act on your code. You open it in a project folder, ask it to explain or change something, and it reads files, runs commands and edits code, with permission prompts for some actions.

What makes OpenCode different from many coding agents is that it isn't tied to one AI company. The providers docs say it supports 75+ providers. You can use your own API key from OpenAI, Anthropic, OpenRouter, Groq and others. The docs also say some subscriptions work with OpenCode, including ChatGPT Plus, GitHub Copilot and GitLab Duo.

Is OpenCode free? The download page FAQ says "OpenCode is 100% free to use. Any additional costs will come from your subscription to a model provider." It also says you "can work with local models for free." The installer we ran printed "OpenCode includes free models, to start," and OpenCode's hosted services also list free, limited-time models. Those limits can change, so don't plan a project around them.

How to install OpenCode (macOS, Linux, Windows)

The docs say: "The easiest way to install OpenCode 1 is through the install script." This is the command they give:

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

We prefer to download the script first, look at it, then run it. That's what we did on Oct 31, 2026:

curl -fsSL https://opencode.ai/install -o install
less install
bash install

Other install options from the docs, checked Oct 31, 2026:

On Windows, OpenCode's troubleshooting page says WSL "provides a Linux environment that works more seamlessly with OpenCode's features."

Then check it worked:

opencode --version

Ours printed 1.19.5. Running opencode --help lists the commands, including providers (alias auth) and uninstall.

To start it, open your project folder and run opencode:

cd my-project
opencode

OpenCode 1 vs OpenCode 2: which one did you install?

There are two major versions right now. The docs warn: "OpenCode 1 and OpenCode 2 both use the opencode command and cannot be installed side by side under their default command."

That matters because the install method decides which one you get. The docs say "Homebrew's brew install opencode formula currently installs V2," while the install script and the anomalyco/tap/opencode formula install V1.

OpenCode's download page (external) now leads with version 2 commands, checked Oct 31, 2026:

curl -fsSL https://opencode.ai/v2/install | bash
npm install -g @opencode/cli
brew install anomalyco/tap/opencode-v2

So if you copied a command from the download page, you probably have version 2. If you followed the docs' install page, as we did, you have version 1.

How to tell: run opencode --version. A 1.x number means OpenCode 1. A 2.x number means OpenCode 2.

How to move to version 2: the CLI docs list this command, which "Upgrade[s] to OpenCode 2 and remove[s] OpenCode 1":

opencode upgrade --major

The steps on this page follow the OpenCode 1 docs, which match what we installed. If you're on 2.x, file paths and commands may differ, so check the version 2 docs first.

How do I connect a model provider?

Inside OpenCode, type /connect, pick a provider and paste your API key. From the command line, the same thing is opencode auth login. We used the command-line form with a fake key:

opencode auth login --provider openai --method "Manually enter API Key"

Then list what's saved:

opencode auth list

Ours printed the credentials file path, one entry ("OpenAI api") and "1 credentials". opencode models lists the models you can use, in provider/model form.

Getting a key. Each provider has its own console. We have guides for OpenRouter API keys and Groq API keys, which work with OpenCode.

Can I use my Claude Pro or Max plan with OpenCode? The OpenCode providers docs say: "There are plugins that allow you to use your Claude Pro/Max models with OpenCode. Anthropic explicitly prohibits this." They add that earlier versions bundled those plugins, "but that is no longer the case as of 1.3.0." Separately, OpenCode's changelog (external) for v2.2.3 (Oct 30, 2026) says: "Added the built-in Claude Agent provider. Install Claude Code, run claude auth login, and select Claude Agent in /connect" It doesn't say which Claude plans that covers, and we didn't test it (we ran version 1.19.5). Both checked Oct 31, 2026. The simplest documented route for Claude models is an Anthropic API key.

Where does OpenCode store my API keys?

The providers docs say: "When you add a provider's API keys with the /connect command, they are stored in ~/.local/share/opencode/auth.json." On Windows, the troubleshooting page gives %USERPROFILE%\.local\share\opencode.

That folder holds more than keys. The troubleshooting docs list:

What we saw. After adding our fake key, we checked the file's permissions and printed it with the key masked:

ls -l ~/.local/share/opencode/auth.json
-rw------- 1 box box 61 Oct 31 06:57 auth.json

The -rw------- means only your user account can read or write it. The contents were plain JSON with the key in readable text (masked here):

{
  "openai": {
    "type": "api",
    "key": "sk-XXXX (masked)"
  }
}

So the key isn't encrypted on disk. It's protected by file permissions, like most CLI tools' credential files. That's fine on your own laptop. It's a risk if you back up your home folder to a shared drive, copy your dotfiles to a public repo, or share a machine.

Other places OpenCode reads keys from. The CLI docs say that at startup, OpenCode loads providers from the credentials file "And if there are any keys defined in your environments or a .env file in your project." So keys can also come from your shell or your project's .env file.

How to keep OpenCode keys out of Git

The main rule: your config can go in Git, your keys can't.

Step 1: reference keys, don't paste them. The config docs say "Use {env:VARIABLE_NAME} to substitute environment variables." Here is the project opencode.json we used:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

The docs say the project config "is also safe to be checked into Git," as long as it holds no raw keys. They also support {file:~/.secrets/openai-key} for "Keeping sensitive data like API keys in separate files."

One catch from the docs: "If the environment variable is not set, it will be replaced with an empty string." That's what happened to us. With {env:OPENAI_API_KEY} in the config and no real key, a test run failed with "Incorrect API key provided: ''".

Step 2: ignore secret files. We added these lines to .gitignore:

.env
.env.*
auth.json
.opencode/

Ignoring .opencode/ is optional. The docs say project plugins live in .opencode/plugins/, so some teams commit that folder. Only commit it if it has no secrets.

Step 3: check before you commit.

git status --short
git check-ignore -v .env

In our test, git status listed only .gitignore, index.ts and opencode.json. The .env file didn't appear, and git check-ignore confirmed the .env rule matched.

If a key already made it into a commit, deleting the file isn't enough. Follow I committed my .env file to Git, rotate the key, and read Is my AI API key stolen?. New to env files? Start with What is a .env file?

Watch the permission prompts. The config docs say: "By default, opencode allows most operations without requiring explicit approval. Some operations, including reading .env files and accessing external directories, require approval." If OpenCode asks to read your .env, think before you say yes. The CLI's --auto flag auto-approves permissions that aren't denied, and our version's help text labels it "dangerous!"

What is AGENTS.md?

Running /init inside OpenCode creates an AGENTS.md file with notes about your project for the agent. The docs say: "You should commit your project's AGENTS.md file to Git." Keep it free of secrets, since it's meant to be shared.

We tried to create one with a non-interactive run, but our fake key made the provider call fail, so no AGENTS.md was written. Here's what that looked like:

What are OpenCode Zen and OpenCode Go?

This is where OpenCode pricing comes in. Both are optional model services run by the OpenCode team. You don't need either one.

• Zen is pay-as-you-go access to a list of tested models, priced per 1M tokens, plus some free limited-time models. The Zen docs list a processing fee of "4.6% + $0.31" per credit purchase, and they note that some free models may use your data to improve the model. They also document an OPENCODE_DISABLE_FREE_MODELS=1 setting.
• Go is a monthly plan for open coding models. The Go docs say "It's completely optional and you don't need it to use OpenCode."

Prices as of Oct 31, 2026. Check the official page before you rely on them.

The Go docs say each model has a 5-hour limit of 20% of the monthly amount and a weekly limit of 50%. If you run out, "you can continue using the free models."

A note on free usage. On Oct 29, 2026, Socket reported on a heated community dispute over how OpenCode enforces its free usage limits. The report says it's "unclear whether OpenCode changed its enforcement." For your setup, the practical point is that free allowances can change without notice. If a project matters, use your own provider key or a paid plan.

OpenCode vs Claude Code

Compared on Oct 31, 2026; based on OpenCode's and Anthropic's public sites (opencode.ai/docs and code.claude.com/docs).

Which one should you use? If you want to switch between model companies or use a cheaper open model, OpenCode is built for that. If you already pay for Claude Pro or Max and want Anthropic's own tool, use Claude Code; OpenCode's docs say using those plans through third-party plugins is prohibited by Anthropic, and its newer Claude Agent provider (v2.2.3) is untested by us. We installed OpenCode for this page but didn't run Claude Code, so this table compares documented features, not quality. For more matchups, see Codex vs Claude Code and Cursor vs Claude Code.

How to uninstall OpenCode

The troubleshooting docs say: "To uninstall the OpenCode CLI and remove its related files, run: opencode uninstall." It shows what it will remove and asks to confirm. The CLI docs list --keep-config, --keep-data, --dry-run and --force options.

opencode uninstall --dry-run
opencode uninstall

Ours detected "Installation method: curl" and removed the data folder (where auth.json lives), the cache, the config and the state folders. It then told us to delete the binary ourselves:

rm ~/.opencode/bin/opencode

After that, opencode was no longer found.

Uninstalling the desktop app. The docs say: "To remove OpenCode Desktop, uninstall the application through your operating system's app management tools." Its settings live in a separate folder, which the docs give as ~/Library/Application Support/ai.opencode.desktop/ on macOS, ~/.config/ai.opencode.desktop/ on Linux and %APPDATA%\ai.opencode.desktop\ on Windows.

Before you uninstall, if you added real keys, revoke them in each provider's console. Deleting auth.json removes the local copy, but the key still works until you revoke it.

FAQ

What is OpenCode (open code)? OpenCode is an open source AI coding agent. Its docs say it's available as a terminal interface, a desktop app or an IDE extension, and it works with many model providers.

Is OpenCode free? The software is open source and free to install. You pay your model provider, or use OpenCode's optional Zen or Go services. Some free models exist, with limits that can change.

How do I install OpenCode? Run curl -fsSL https://opencode.ai/install | bash, or npm install -g opencode-ai. Then run opencode --version to check it worked.

Where does OpenCode store API keys? Keys added with /connect or opencode auth login go to ~/.local/share/opencode/auth.json. It's plain JSON protected by file permissions, so keep it out of Git and backups.

How do I uninstall OpenCode desktop? OpenCode's docs say to remove the desktop app with your operating system's app management tools. For the CLI, run opencode uninstall.

Can I open OpenCode in VS Code? OpenCode's docs list an IDE extension, and you can also run opencode in VS Code's built-in terminal from your project folder. We didn't test the extension.

How do I install the OpenCode desktop app? The opencode.ai download page lists installers for macOS, Windows and Linux (.deb, .rpm), plus brew install --cask opencode-desktop. We tested only the CLI.

Can I use my Claude Pro or Max subscription with OpenCode? OpenCode's docs say Anthropic "explicitly prohibits" using Pro/Max plugins. Per the v2.2.3 changelog, a new Claude Agent provider uses your Claude Code login. We didn't test it.

Built your app with an AI coding agent? Keep keys in env vars, check git status before every push, and run a free scan with Greenlight My App to check your live site's public code for exposed API keys and missing security headers.