Terminal-based AI coding agents keep multiplying, and most of them lock you into one model or one vendor. OpenCode takes the opposite approach: a fast, open-source agent that runs entirely in your terminal and talks to whatever LLM provider you point it at, from Anthropic and OpenAI to local models. It reads your project, edits files, runs commands, and reasons about your codebase without shipping your code to a proprietary cloud service.
This guide installs OpenCode on both Rocky Linux and Ubuntu, points it at a provider with an API key, and gets you to a working first session. Every command was run on Rocky Linux 10 and Ubuntu 26.04 with opencode 1.18.4 in July 2026, and the output below is captured from those installs.
What you’ll learn
- Install OpenCode on Rocky Linux / RHEL and Ubuntu / Debian
- Install with the official script or the npm package
- Point OpenCode at Anthropic, OpenAI, or a local model with an API key
- Verify the install and confirm your provider is connected
- Run your first session in the TUI and non-interactively with
opencode run - Use plan mode and generate an
AGENTS.mdso the agent respects your project rules
Prerequisites
- A Linux machine running Rocky Linux 9.x/10 or RHEL, or Ubuntu 24.04+/Debian 12+
- A regular user with sudo access
- An API key from at least one provider (Anthropic, OpenAI, OpenRouter, or a local model via Ollama)
- Node.js and npm only if you install through npm; the official script needs no runtime
- Tested on: Rocky Linux 10 and Ubuntu 26.04
What is OpenCode?
OpenCode is an open-source AI coding agent that lives in your terminal, maintained by Anomaly at github.com/anomalyco/opencode under the MIT license. The name has some history worth knowing: the original project was written in Go, and after a 2025 governance dispute that fork became Charm’s “Crush”, while the team behind SST kept the OpenCode name and rewrote it in TypeScript. That TypeScript rewrite is the tool this guide installs. Older links to sst/opencode now redirect to the Anomaly repository.
OpenCode is provider-agnostic. It reaches 75+ model providers through the Models.dev catalog, so you can run Claude for heavy reasoning, a cheaper model for quick edits, or a local model through Ollama for air-gapped work, all from the same binary.
Install OpenCode on Rocky Linux / RHEL
The official installer downloads a single standalone binary and adds it to your PATH. No Node.js runtime is required for this path. Make sure curl is present on RHEL-family systems first:
sudo dnf install -y curlRun the installer:
curl -fsSL https://opencode.ai/install | bashThe script detects your architecture, drops the binary in ~/.opencode/bin, and prints a short getting-started hint. If ~/.opencode/bin is not already on your PATH, open a new shell or source your profile so the opencode command resolves.
Install OpenCode on Ubuntu / Debian
The same script works on Debian-based systems. Ubuntu ships curl by default, but install it if your image is minimal:
sudo apt update && sudo apt install -y curlThen run the installer and confirm the binary resolved:
curl -fsSL https://opencode.ai/install | bash
which opencode
opencode --versionOn a fresh Ubuntu 26.04 box the binary lands under your home directory and reports the current version:
If you would rather manage it with a package manager, the npm package is named opencode-ai (not opencode), and Homebrew, Scoop, and the AUR are supported too. The npm route needs a working Node.js and npm:
npm install -g opencode-aiBoth methods install the same binary. The curl script is the simplest because it handles the PATH entry for you.
Point OpenCode at a provider
OpenCode needs at least one provider before it can do anything useful. The interactive path walks you through it:
opencode auth loginPick a provider from the list, paste your API key, and it is stored locally under ~/.local/share/opencode/auth.json with restricted permissions. List what is configured at any time:
opencode auth listFor a scripted or CI setup, keep the key in an environment variable and reference it from a config file so the secret never lives in the repo. Create the config:
vim ~/.config/opencode/opencode.jsonSet your default model and pull the key from the environment:
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-5",
"provider": {
"anthropic": { "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" } }
}
}Export the key in your shell (or drop it in a project .env), and opencode substitutes it at runtime:
export ANTHROPIC_API_KEY="your-api-key-here"The model identifier always follows the provider/model format. Swap Anthropic for openai/gpt-..., google/gemini-..., or a local Ollama model by changing that one string.
Your first session
Change into a project and start the TUI:
cd ~/my-project
opencodeThe first thing to run inside a new project is /init. It scans the codebase and writes an AGENTS.md file that gives the agent persistent rules about your stack, conventions, and build commands. From there, describe what you want in plain language.
Press Tab to toggle between Build and Plan mode. Plan mode disables file edits and has the agent propose an approach first, so you approve the shape of a change before anything is written. That single habit prevents most “why did it rewrite twelve files” surprises.
For scripting and CI, skip the TUI entirely with opencode run, which takes a one-shot prompt and exits:
opencode run --model anthropic/claude-sonnet-4-5 "Add a health-check endpoint to the Flask app and a unit test for it."Useful flags on run include -m/--model to override the model, --agent to pick a specific agent, --format json for machine-readable events, and --share to generate a shareable session link. For DevOps use cases, our guide on using AI coding agents for Terraform, Ansible, and Kubernetes walks through real infrastructure prompts.
Troubleshooting
“opencode: command not found” after install
The binary installs to ~/.opencode/bin, which the script adds to your shell profile. If the command does not resolve, your current shell has not picked up the change. Open a new terminal, or add the directory to PATH for the session:
export PATH="$HOME/.opencode/bin:$PATH"“no provider configured”
OpenCode cannot start a session without a model provider. Run opencode auth login and add a key, or confirm your opencode.json references an environment variable that is actually exported in the current shell. Verify with opencode auth list.
A note on multi-agent orchestration
OpenCode has built-in subagents and plan mode, which handle most delegation on their own. If you specifically want a heavier orchestration layer that coordinates several specialized agents across a task, Oh My OpenAgent is an independent third-party project that layers that workflow on top of OpenCode. It is a separate tool with its own install and configuration, not part of OpenCode itself, and nothing in this guide depends on it.
FAQ
How much does OpenCode cost?
OpenCode itself is free and open source under MIT. The cost is whatever your model provider charges for API usage. A session that touches a handful of files typically costs a few cents to a couple of dollars depending on the model, with larger reasoning models being the expensive part. You can keep costs down by setting a cheaper default model and only reaching for a bigger one when a task needs it.
Do I need more than one provider?
No. A single provider is enough to use every feature. Multiple providers are handy if you want to route heavy reasoning to one model and cheap edits to another, but that is an optimization, not a requirement. Switch models any time with /models in the TUI or the -m flag on opencode run.
Can I run OpenCode alongside Claude Code?
Yes. They use separate config directories (~/.config/opencode/ vs ~/.claude/) and separate authentication, so they do not conflict on the same machine or even the same project. Many developers keep both and reach for whichever fits the task. Our Claude Code cheat sheet covers that workflow, and the OpenCode CLI cheat sheet is the working reference once you are set up.
