OpenCode on Ubuntu: A Self-Hosted Coding Agent

OpenCode (formerly sst/opencode, now anomalyco/opencode) is a provider-agnostic, open-source terminal coding agent. It’s MIT-licensed, has provider adapters for Anthropic, OpenAI, Google, Bedrock, Vertex, Groq, and any OpenAI-compatible API (Ollama, LM Studio, OpenRouter), and at v1.17.20 it ships with a polished TUI, multi-session support, and an LSP-aware edit pipeline. This article shows the install, the minimum provider setup, and the day-one workflow.

Install on Ubuntu 22.04 / 24.04

OpenCode ships an official installer bash script:

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

It auto-detects your OS/arch, downloads a single binary to ~/.opencode/bin/, and appends one PATH line to your shell rc. Source it or open a new terminal:

opencode --version
opencode --help

The npm alternative (same version, source available):

npm i -g opencode-ai@latest

There’s also a Linux Brew tap (brew install anomalyco/tap/opencode) if you prefer that path.

Pick a provider

OpenCode is BYOK and multi-provider. Configure one (or several):

opencode config set provider anthropic
opencode config set model claude-sonnet-4-2026

opencode config set provider openai
opencode config set base_url http://localhost:11434/v1
opencode config set model qwen3:30b-a3b

API keys go in ~/.opencode/.env (the installer doesn’t read your shell env) or via the --api-key flag on a per-session basis. Multiple providers can stay configured; Ctrl+P inside the TUI switches between them mid-session.

First session

cd ~/work/my-app
opencode

You land in the TUI: a session sidebar on the left, chat on the right. Type a request. Three starter questions to ask:

1. “Walk me through the structure of this repo.” — uses OpenCode’s repo map, which is fast and surprisingly good at large monorepos.
2. “Refactor <file> to use the new error pattern in errors.ts.” — OpenCode uses LSP diagnostics on every edit, so broken types flag immediately.
3. “Add an integration test for <feature>.” — gives you a sense of OpenCode’s spec-and-implement loop.

The TUI keybindings you’ll want: Tab (accept suggestion), Shift+Tab (cycle mode), Ctrl+P (commands), / (command palette), ? (full keymap).

What makes OpenCode different from Claude Code

Both are terminal-native and use the same Anthropic models, but they diverge on three axes:

• Provider-agnostic: switching between Anthropic, OpenAI, Groq, Ollama, or an OpenRouter proxy is a config line, not a different product. Anthropic isn’t the only game in town; OpenCode respects that.
• MIT-licensed core: you can fork it, audit it, run it behind a strict firewall. Crucial for compliance-heavy teams.
• TUI-first, no Electron overlay: lighter than Claude Code’s terminals-plus-desktop split. There’s a desktop build (opencode desktop) but it’s optional.

Day-to-day patterns that work

• Multi-session: use the sidebar to keep parallel contexts — one session for active development, one for review, one for research.
• Custom commands: drop Markdown prompt templates in ~/.opencode/commands/. They’re slash-invokable like Claude Code’s.
• Plugins: opencode plugin install <name> for in-process extensions (TypeScript modules). Public registry is small but growing.

When to pick OpenCode over alternatives

• You want provider flexibility (BYOK + local) without maintaining a fork.
• The team is OK with MIT-licensed tools over closed-source Claude Code.
• You primarily live in a TUI, not an IDE.

If you’re already a heavy Claude Code user and like its plan-first defaults, OpenCode supports those via /plan — but the ecosystem around them (skills, MCP marketplace) is still catching up.