Installation and First Setup

Beginner⏱30 min📖3 min readLesson 2 of 5

Installation and First Setup

Install OpenCode on your system and configure it with your first LLM provider. Set up API keys, verify the installation, and run your first command.

Prerequisites

Before installing OpenCode, ensure you have:

Requirement	Minimum Version	How to Check
Node.js	18.0+	`node --version`
npm	8.0+	`npm --version`
Git	2.0+	`git --version`

ℹ️Note

OpenCode is a Node.js application distributed via npm. It runs on macOS, Linux, and Windows.

Installation

Using npm (Recommended)

bash

npm install -g opencode

Using yarn

bash

yarn global add opencode

Using pnpm

bash

pnpm add -g opencode

Verify Installation

bash

opencode --version

Expected output:

opencode v1.x.x

💡Tip

If you see "command not found", ensure npm's global bin directory is in your PATH.

Initial Configuration

Step 1: Create Configuration Directory

bash

mkdir -p .opencode

Step 2: Create opencode.json

Create opencode.json in your project root:

json

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "General-purpose coding assistant"
    }
  }
}

Step 3: Set Up API Keys

Create a .env file in your project root:

bash

# OpenAI
OPENAI_API_KEY=sk-your-api-key-here

# Anthropic (optional)
ANTHROPIC_API_KEY=sk-ant-your-api-key-here

# Google (optional)
GOOGLE_API_KEY=your-google-api-key-here

⚠️Warning

Never commit API keys to version control. Add .env to your .gitignore file.

Provider Configuration

OpenAI

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o"
    }
  }
}

Anthropic

json

{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514"
    }
  }
}

Google

json

{
  "providers": {
    "google": {
      "apiKey": "${GOOGLE_API_KEY}",
      "model": "gemini-pro"
    }
  }
}

First Run

Start OpenCode

bash

opencode

You should see:

OpenCode v1.x.x
Type your message or /help for commands
>

Test the Connection

Type a simple message:

> Hello, can you help me with my code?

If successful, the AI will respond with a greeting and ask how it can help.

Configuration File Locations

OpenCode searches for configuration in this order:

Priority	Location	Purpose
1	`.opencode/config.json`	Project-specific (preferred)
2	`opencode.json`	Project-specific (legacy)
3	`~/.config/opencode/config.json`	User-wide defaults

💡Tip

Use .opencode/config.json for team projects. You can selectively version-control it while keeping sensitive data in .env.

Basic Commands

Command	Description
`opencode`	Start interactive session
`opencode --version`	Show version
`opencode --help`	Show help
`opencode config`	Open configuration
`opencode providers`	List available providers

Troubleshooting

Common Issues

Issue	Cause	Solution
"Command not found"	npm PATH not set	Run `npm config get prefix` and add to PATH
"Invalid API key"	Wrong key format	Check key starts with `sk-` (OpenAI) or `sk-ant-` (Anthropic)
"Rate limit exceeded"	Too many requests	Wait or upgrade your API plan
"Model not found"	Wrong model name	Check provider documentation for valid model names