Open source · Provider-agnostic · Runs on the OS you already trust
A coding agent you run yourself.
opencode is an open-source CLI that lets an AI read your code, propose edits, run commands, and ship pull requests — directly from your Linux terminal. It runs against your favourite models, on your machine, with your data staying where you put it. This page is the Linux Institute guide to actually using it.
Edits you can read before they land.
opencode proposes diffs before it writes anything. You approve, edit, or reject each one. The terminal is the review surface.
What we're building
An AI that lives inside your terminal.
opencode is a Textual-based TUI plus a headless CLI that you point at a repo. It reads files, edits them, runs tests, calls tools, and hands back a diff. It is one of several open-source agents in this category — comparable in shape to Claude Code, less polished at the edges, and tunable in ways that the closed-source alternatives are not.
VS Code
The opencode VS Code extension wires the agent into the editor's sidebar, with inline diffs and one-click apply.
You run it inside the directory you want worked on. Files, env vars, git, npm, pytest — everything the terminal already knows about, opencode already knows about.
⌥
PROVIDER AGNOSTIC
Bring your own model.
Wire it up to Anthropic, OpenAI, Google, OpenRouter, or a self-hosted Ollama / vLLM endpoint. Cost and quality are your choice, not the agent’s.
⌥
DIFFS, NOT MAGIC
Every change is reviewable.
opencode proposes edits as diffs before writing them. You approve, edit, or reject each block. The terminal is the review surface; the result is a normal git commit.
⊕
PLUGGABLE TOOLS
MCP servers, your tools.
Wire in your GitHub, Postgres, browser, custom internal API. Anything that speaks the Model Context Protocol becomes a tool opencode can call.
Install
Three minutes, one command.
The recommended install is a single shell command. No package manager fight, no hidden services, no daemon.
NPM
If you already have Node
npm i -g opencode-ai@latest
opencode --version
Recommended for Linux distros where Node is already installed for other tooling.
A static-ish install script. Lands at ~/.opencode/bin/opencode. Add it to PATH if your shell doesn’t find it.
If you prefer not to install anything system-wide, Docker is also viable: docker run -it --rm -v $(pwd):/app ghcr.io/sst/opencode opencode.
Verify the install.
smoke test$ opencode --version
opencode 0.x.y$ opencode auth list
default anthropic ✓ logged inbackup openrouter ✓ logged inlocal ollama ✓ reachable at http://127.0.0.1:11434# Now point it at a repo and ask for something small.$ cd ~/code/personal/dotfiles
$ opencode run 'Add a bootstrap script for new machines and commit it.'
→ reading repo structure→ proposed 2 edits (use --yes to apply)! inspection: open bootstrap.sh
✓ applied✓ git commit -m 'feat: add bootstrap script for new machines'
First session
The first five minutes.
Once installed, the first run is the longest because you choose models and sign in. Subsequent sessions are pure terminal muscle memory.
Pick a project directory
cd into a real project. opencode scans the tree before it answers, so context matters.
Run opencode
The TUI launches. Use it for multi-turn work, swapping models, resuming sessions.
Or run opencode run 'task'
Bounded, one-shot mode for automation. Exits when done. Perfect for cron jobs and CI.
Review every diff
Approve, edit, or reject each block. Don’t accept a diff you cannot read.
Why on Linux specifically
Linux is the agent’s home turf.
opencode will work anywhere, but Linux is where it has the least friction. The reasons are unglamorous and add up.
Self-host, in your cupboard.
opencode + Ollama on the same Linux box gives you a fully offline coding agent. No data leaves your network.
Five things Linux gives you for free.
POSIX terminal semantics.opencode runs Bash, redirects output, pipes commands. It is a first-class citizen of the same shell you already use.
No sandbox theatre.You pick what the agent can touch. Run it inside a container, a chroot, a VM, or nothing — your choice, your ~/.bashrc.
Local LLM endpoints.Ollama and vLLM install with one command. opencode talks to them over HTTP like any other provider.
Reproducible installs.Pin opencode in your flake.nix, Dockerfile, or Ansible playbook. Every team member gets the same version.
SSHable from anywhere.Run opencode on a server, attach to it from your laptop over SSH. Coding agents stop being laptop-bound.
Autonomy patterns
Three ways to use opencode.
Most teams settle into one of three rhythms. Pick the one that matches how cautious you want to be about code you didn’t personally write.
CAUTIOUS
Review-the-diff
You write a ticket-level prompt. opencode proposes a diff. You read every change, edit what doesn’t match, approve. Nothing lands without your eyes on it.
Best for: Production codebases, junior teams, anything where you can’t lose the weekend to a botched rewrite.
COLLABORATIVE
Pair-programming
You open the TUI and iterate in real time. “Make the test pass.” “Add a TypeScript type.” “Why did you pick this approach?” Treat opencode as a junior pair, not a contractor.
Best for: Refactors, exploratory work, learning a new codebase alongside a real engineer.
AUTONOMOUS
Background workers
Run opencode run 'fix the failing CI job' from cron. Read the diff in the morning. Same shape as the cautious mode — but the trigger is your scheduler, not your fingers.
Best for: Bulk migrations, dependency upgrades, integration tests nobody writes by hand.
Providers
Bring the model you trust.
opencode is provider-agnostic at the API level. Configure multiple, switch with one keystroke, fall back automatically.
Provider
What it gives you
When to reach for it
Anthropic Claude
Strong reasoning and large context. Strongest out-of-the-box default for coding.
Daily driver, paid plan or API key.
OpenAI
Broad model line-up, generous limits, ecosystem fit.
You already pay for ChatGPT Plus or have an API key.
Google Gemini
Very large context window, multimodal inputs.
You want to drop entire repos into the prompt.
OpenRouter
Single API for many models. Easiest way to A/B test.
Comparing models or hedging against single-vendor lock-in.
Ollama (local)
Open-weight models on your hardware. Fully offline.
You keep code on disk and want it to stay there.
vLLM (local)
High-throughput local inference for serious models.
Your team has a GPU server and wants shared local capacity.
configuring a default model# ~/.config/opencode/config.yamlproviders:anthropic:apiKey: $ANTHROPIC_API_KEY
defaultModel: claude-sonnet-4
ollama:baseUrl: http://127.0.0.1:11434
defaultModel: qwen2.5-coder:32b
# Switch with one keystroke inside the TUI: <leader>+m# Or per-call from the CLI:$ opencode run '...task...' --model ollama/qwen2.5-coder:32b
Going offline
Self-hosting the whole stack.
For teams that cannot send code off-site, opencode + Ollama + a Linux box is the whole story. Three commands, no external network calls.
local-only deployment# 1. Install Ollama$ curl -fsSL https://ollama.com/install.sh | sh
$ ollama pull qwen2.5-coder:32b
✓ 32B model downloaded, ~20 GB# 2. Install opencode$ npm i -g opencode-ai@latest
# 3. Configure$ opencode auth login --provider ollama
✓ reachable at http://127.0.0.1:11434# 4. Disable any provider config that hits the internet$ opencode run 'summarise the spec in ./docs' \
--model ollama/qwen2.5-coder:32b \
--no-network
That configuration works on a Raspberry Pi 5 with 8 GB of RAM for the small models (qwen2.5-coder:7b), on an M-series Mac, on any Linux box with a discrete GPU for the bigger models, and on remote boxes you SSH into over WireGuard.
Pitfalls
What goes wrong, and how to avoid it.
The same five things go wrong across most teams adopting coding agents. Pre-empt them and you’ll move twice as fast.
1. Letting the agent pick what to touch.
Pin scope. “Edit only src/auth/, don’t touch tests.” The fastest way to break a green CI is to let the agent rewrite tests.
2. Skipping the diff.
Always read. If a diff is bigger than ~150 lines, send the agent back with “smaller changes only”.
3. Letting secrets leak into the prompt.
Keep .env in ~/.gitignore, keep it out of the agent’s context. Add a PreToolUse hook to deny reads of .env and ~/.ssh/.
4. Trusting a flaky model.
Some models confidently invent function names that don’t exist in your codebase. The reviewer is you. The diff is the audit log.
5. Committing without testing.
Always run the suite after a non-trivial change. Many agents have a “run the tests and fix what’s red” follow-up. Use it.
6. Forgetting the bill.
Autonomous runs eat tokens. Cap spend with --max-budget-usd 1 (or use Ollama).
FAQ
Common questions.
Is opencode production-ready?
It is stable enough for daily use by experienced engineers who read every diff. It is not yet a polished product comparable to a paid SaaS. Expect rough edges, especially around long-running sessions and model-specific quirks.
How is it different from Claude Code?
Same shape — terminal-based agent that reads code, proposes diffs, runs commands. opencode is open-source, provider-agnostic, and self-hostable. Claude Code is closed-source, only Anthropic models, and has a more polished TUI. Pick opencode for tunability and on-prem; pick Claude Code for the smoothest plug-and-play.
Can I use it on Windows?
Yes — Windows and macOS are first-class targets. Linux is where it is most deeply integrated (POSIX, Docker, Ollama, systemd).
Does my code go anywhere?
By default, prompts go to the model provider you configure. If you use Ollama locally, your code never leaves your network. read the opencode privacy posture for whichever provider you pick.
Where does it store conversation history?
Locally, in ~/.local/share/opencode/. Sessions are plain JSON you can grep, version-control, or delete.
Will it work against proprietary internal tools?
Yes, via MCP. Build a tiny MCP server that wraps your internal API and opencode will call it the same way it calls any other tool.
Where to go next
From opencode --version to first commit.
If you want a structured walkthrough — install, provider, MCP, hooks, full repo migration — subscribe to Deep Tabs. If you want to self-host the whole stack on a Raspberry Pi, the Private Cloud page covers it.
VS Code
Docker
