Skip to main content

Quick Start Guide: Getting Started with OpenCode

Welcome to the OpenCode Quick Start Guide. This document provides a comprehensive walkthrough to get you up and running with OpenCode, a powerful AI coding assistant designed to live directly in your terminal. By the end of this guide, you will have installed OpenCode, configured it to use a powerful AI model, and learned the core workflow for using it to read, understand, and modify a codebase.

1. Introduction​

OpenCode is a 100% open-source, provider-agnostic AI coding agent that lives in your terminal. It is designed for developers who want to leverage the power of large language models without being locked into a specific ecosystem. With OpenCode, you can bring your own API key and use models from over 75 providers, including local models.

2. Installation​

cURL​

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

Package managers​

npm i -g opencode-ai@latest        # or bun/pnpm/yarn
brew install sst/tap/opencode      # macOS and Linux
paru -S opencode-bin               # Arch Linux

3. Authentication​

OpenCode supports over 75 LLM providers. Here are a few examples of how to set up some of the most popular ones.

Anthropic​

We recommend signing up for Claude Pro or Max, it’s the most cost-effective way to use opencode.

Once you’ve singed up, run opencode auth login and select Anthropic.

$ opencode auth login

┌  Add credential
│
◆  Select provider
│  ● Anthropic (recommended)
│  ○ OpenAI
│  ○ Google
│  ...
└

Here you can select the Claude Pro/Max option and it’ll open your browser and ask you to authenticate.

$ opencode auth login
┌  Add credential
│
◇  Select provider
│  Anthropic
│
◆  Login method
│  ● Claude Pro/Max
│  ○ Create API Key
│  ○ Manually enter API Key
└

Now all the the Anthropic models should be available when you use the /models command.

Using API keys​

You can also select Create API Key if you don’t have a Pro/Max subscription. It’ll also open your browser and ask you to login to Anthropic and give you a code you can paste in your terminal.

Or if you already have an API key, you can select Manually enter API Key and paste it in your terminal.

Azure OpenAI​

Head over to the Azure portal and create an Azure OpenAI resource. You’ll need:

  • Resource name: This becomes part of your API endpoint (https://RESOURCE_NAME.openai.azure.com/)
  • API key: Either KEY 1 or KEY 2 from your resource

Go to Azure AI Foundry and deploy a model.

Note

The deployment name must match the model name for opencode to work properly.

Run opencode auth login and select Azure.

$ opencode auth login

┌  Add credential
│
◆  Select provider
│  ● Azure
│  ...
└

Enter your API key.

$ opencode auth login

┌  Add credential
│
◇  Select provider
│  Azure
│
◇  Enter your API key
│  _
└

Set your resource name as an environment variable:

AZURE_RESOURCE_NAME=XXX opencode

Or add it to a .env file in the project root:

AZURE_RESOURCE_NAME=XXX

Or add it to your bash profile:

export AZURE_RESOURCE_NAME=XXX

Run the /models command to select your deployed model.

Cerebras​

Head over to the Cerebras console, create an account, and generate an API key.

Run opencode auth login and select Cerebras.

$ opencode auth login

┌  Add credential
│
◆  Select provider
│  ● Cerebras
│  ...
└

Enter your Cerebras API key.

$ opencode auth login

┌  Add credential
│
◇  Select provider
│  Cerebras
│
◇  Enter your API key
│  _
└

Run the /models command to select a model like Qwen 3 Coder 480B.

DeepSeek​

Head over to the DeepSeek console, create an account, and click Create new API key.

Run opencode auth login and select DeepSeek.

$ opencode auth login

┌  Add credential
│
◆  Select provider
│  ● DeepSeek
│  ...
└

Enter your DeepSeek API key.

$ opencode auth login

┌  Add credential
│
◇  Select provider
│  DeepSeek
│
◇  Enter your API key
│  _
└

Run the /models command to select a DeepSeek model like DeepSeek Reasoner.

4. Core Workflow​

The primary way to use OpenCode is to cd into your project's root directory and run the opencode command. This launches the terminal user interface (TUI) and begins a session.

opencode

Initialize the Agent​

The first time you run opencode in a new project, it will create a file named AGENTS.md in a .opencode directory. This file is crucial for providing context to the AI. You can edit this file to give the agent specific instructions, context about your project, or define the persona you want it to adopt.

Ask Questions​

Once inside the TUI, you can ask questions about your codebase. For example:

> What is the purpose of the useReducer hook in React?

Making Changes with /plan and /build​

OpenCode uses a powerful two-step process for making changes to your code: Plan and Build.

  • Plan Mode (/plan): First, describe the feature you want to add. OpenCode will analyze the codebase and propose a detailed plan of action.
  • Build Mode (/build): Once you approve the plan, OpenCode will execute it, making the necessary changes to your files.

5. Next Steps​

This guide covers the basics to get you started. For more advanced topics, such as custom themes, keybindings, and a full command reference, please explore the rest of the official OpenCode documentation.