**Meta Description:** Learn how to install, configure, and use OpenCode AI in your terminal. Step-by-step tutorial for beginners to get the open-source AI coding agent running in under 5 minutes.
**Target Keywords:** opencode ai, opencode ai tutorial, ai terminal tool, ai coding agent, opencode setup, opencode install
**URL Slug:** `/opencode-ai-terminal-setup-guide`
**Estimated Reading Time:** 5 minutes
—
## What is OpenCode AI?
OpenCode AI is a free, open-source AI coding agent that runs directly in your terminal. With over 120,000 GitHub stars, it’s become one of the most popular AI development tools in 2026. Unlike proprietary tools that lock you into a single ecosystem, OpenCode supports **75+ LLM providers** including OpenAI GPT, Google Gemini, and local models via Ollama.
Whether you’re a seasoned developer or just getting started with AI-assisted coding, OpenCode brings the power of large language models directly into your command-line workflow.
—
## Prerequisites
Before you begin, make sure you have:
– **Operating System:** macOS 12+, Linux (any modern distro), or Windows 10/11 (WSL recommended)
– **Node.js 18+** (required for some language servers and npm installation)
– **Git** installed for project-level configurations
– **Modern terminal emulator** with true color support (Windows Terminal, WezTerm, Alacritty, Ghostty, or Kitty)
– **API key** from a supported provider (optional if using free built-in models)
—
## Step 1: Install OpenCode AI
OpenCode offers multiple installation methods. Choose the one that best fits your workflow.
### Method 1: Quick Install Script (Recommended)
The fastest way to install OpenCode is using the official one-liner. It automatically detects your OS and architecture:
“`bash
curl -fsSL https://opencode.ai/install | bash
“`
### Method 2: Using npm
If you have Node.js installed, you can install OpenCode globally via npm:
“`bash
npm install -g opencode-ai
“`
### Method 3: Using Homebrew (macOS/Linux)
For macOS and Linux users with Homebrew:
“`bash
brew install anomalyco/tap/opencode
“`
> **Pro Tip:** The official OpenCode tap provides the most up-to-date releases. The standard `brew install opencode` formula is maintained by the Homebrew team and updates less frequently.
### Method 4: Windows Installation
**Using Scoop:**
“`bash
scoop install opencode
“`
**Using Chocolatey:**
“`bash
choco install opencode
“`
**Using npm:**
“`bash
npm install -g opencode-ai
“`
### Method 5: Docker (Try Without Installing)
Want to test OpenCode without installing? Use Docker:
“`bash
docker run -it –rm ghcr.io/anomalyco/opencode
“`
### Verify Your Installation
After installation, verify everything is working:
“`bash
opencode –version
opencode –help
“`
—
## Step 2: Configure Your AI Provider
OpenCode is provider-agnostic, meaning you can use any LLM you prefer. Here are your options:
### Option 1: OpenCode Zen (Easiest – Free Models)
The simplest way to get started is with OpenCode Zen, which provides curated AI models optimized for coding:
“`bash
opencode auth login –provider zen
“`
### Option 2: GitHub Copilot
If you have a GitHub Copilot subscription:
“`bash
opencode auth login –provider github
“`
### Option 3: OpenAI (ChatGPT Plus/Pro Users)
For OpenAI users:
“`bash
opencode auth login –provider openai
“`
### Option 4: Other Providers (Anthropic, Google, etc.)
For interactive setup with other providers:
“`bash
opencode auth login
“`
Or authenticate directly:
“`bash
opencode auth login –provider anthropic
opencode auth login –provider google
“`
### Option 5: Interactive TUI Setup
You can also configure providers from within the terminal UI:
1. Launch OpenCode: `opencode`
2. Run the `/connect` command
3. Select your provider
4. Enter your API key when prompted
Credentials are stored locally in `~/.local/share/opencode/auth.json`.
—
## Step 3: Initialize Your Project
To help OpenCode understand your codebase and provide better assistance, initialize your project:
### From the Terminal
“`bash
cd /path/to/your/project
opencode init
“`
### From the TUI
“`bash
cd /path/to/your/project
opencode
“`
Then type `/init` inside the interface.
This command analyzes your project structure and creates an `AGENTS.md` file in your project root with custom instructions tailored to your codebase.
—
## Step 4: Start Using OpenCode
### Launch the Terminal UI (TUI)
Navigate to your project and run:
“`bash
cd /path/to/your/project
opencode
“`
You’ll be greeted with an interactive terminal interface where you can:
– Ask questions about your code
– Request code modifications
– Debug issues
– Generate new files and features
### Non-Interactive Mode (Scripting & Automation)
For quick tasks without launching the full TUI:
“`bash
opencode run “Explain how closures work in JavaScript”
“`
You can also pass file context:
“`bash
opencode run –file path/to/file.js “Refactor this function”
“`
### IDE Integration
Use OpenCode directly in VS Code or Cursor:
1. Open your terminal in the IDE
2. Run `opencode`
3. Press `Ctrl+Esc` (Windows/Linux) or `Cmd+Esc` (Mac) to open in split view
—
## Essential Commands Cheat Sheet
| Command | Description |
|———|————-|
| `opencode` | Launch the TUI |
| `opencode run “prompt”` | Run a single prompt non-interactively |
| `opencode serve` | Start a headless API server |
| `opencode web` | Start server with web interface |
| `/init` | Initialize project and create AGENTS.md |
| `/connect` | Configure AI provider |
| `/new` | Create a new session |
—
## Advanced Configuration
### Global Configuration File
Create a global config at `~/.config/opencode/opencode.json`:
“`json
{
“providers”: {
“openai”: {
“name”: “OpenAI”,
“options”: {
“apiKey”: “your-api-key-here”
},
“models”: {
“gpt-4o”: {
“name”: “GPT-4o”
}
}
}
}
}
“`
### Project-Specific Configuration
Create an `opencode.json` file in your project root for team-shared settings.
—
## Troubleshooting Common Issues
**Terminal Rendering Issues:** Ensure you’re using a modern terminal emulator with true color support. Older terminals like macOS Terminal.app may have display problems.
**Installation Errors on Windows:** WSL is recommended for the best experience. If using native Windows, try Scoop or Chocolatey.
**Provider Authentication Failed:** Double-check your API key and ensure it has the correct permissions. Run `opencode auth login` to re-authenticate.
—
## Why Choose OpenCode AI?
– **Open Source:** Fully transparent and community-driven
– **Provider Flexibility:** Switch between 75+ LLM providers
– **Free Options:** Use built-in Zen models without any API keys
– **Cross-Platform:** Works on macOS, Linux, and Windows
– **Multiple Interfaces:** Terminal UI, desktop app, IDE extension, and web interface
– **Local Models:** Privacy-focused option with Ollama integration
—
## Next Steps
Now that you have OpenCode set up, explore these resources:
– **Official documentation:** [opencode.ai/docs](https://opencode.ai/docs)
– **GitHub repository:** [github.com/anomalyco/opencode](https://github.com/anomalyco/opencode)
– **Desktop app download:** [opencode.ai/download](https://opencode.ai/download)
—
*Have you tried OpenCode AI? Share your experience in the comments below!*