beginner⏱30 minLesson 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.

Installation and First Setup

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

Practice Questions

Practice Question

What is the minimum Node.js version required for OpenCode?

Practice Question

Where should you store API keys for OpenCode?

Practice Question

Which configuration file location is recommended for team projects?

Practice Question

What command starts an interactive OpenCode session?

Practice Question

Which package managers can be used to install OpenCode?

✅Success

Key Takeaways

OpenCode requires Node.js 18+ and can be installed via npm, yarn, or pnpm
Configuration is stored in opencode.json or .opencode/config.json
API keys should be stored in environment variables or .env files
The .opencode/config.json location is preferred for team projects
Run opencode to start an interactive session
Multiple LLM providers (OpenAI, Anthropic, Google) are supported

Progress40%

What is OpenCode and Why Use It

Your First AI Coding Session

Course Content

1. What is OpenCode and Why Use It 2. Installation and First Setup 3. Your First AI Coding Session 4. Understanding the CLI Interface 5. Basic Configuration with opencode.json