Lab 2.1: Install OpenCode & Set Up a Model Provider¶

Goal¶

By the end of this lab, you will: 1. Install OpenCode on your machine (macOS, Linux, or Windows-WSL). 2. Create an API key with a model provider (Anthropic, OpenAI, or local Ollama). 3. Configure OpenCode to use that provider. 4. Complete your first task: fix a typo in a code sample.

Estimated time: 30 minutes.

Part A: Install OpenCode¶

Option A1: macOS (Homebrew)¶

If you have Homebrew installed:

brew install opencode

To verify:

opencode --version

You should see something like opencode 0.15.0 (or your installed version).

Option A2: Linux (apt, dnf, or from source)¶

Ubuntu/Debian:¶

curl -sSL https://opencode.ai/install.sh | bash

Or, if you use apt:

sudo apt-get update
sudo apt-get install opencode

Verify:

opencode --version

Fedora/RHEL:¶

sudo dnf install opencode

Verify:

opencode --version

From source (any Linux):¶

If the above don't work, install from source:

git clone https://github.com/opencode/opencode.git
cd opencode
cargo build --release
sudo cp target/release/opencode /usr/local/bin/

Verify:

opencode --version

Option A3: Windows (WSL or Direct)¶

WSL (Windows Subsystem for Linux) — Recommended¶

If you have WSL set up, open your WSL terminal and follow the Linux instructions above (Ubuntu is the most common).

Windows (Direct, no WSL)¶

Download the installer from opencode.ai/download:

Visit https://opencode.ai/download
Download the Windows installer (.exe or .msi)
Run it
Follow the installer prompts
Open a new cmd.exe or PowerShell and verify:
```
opencode --version
```

Troubleshooting Installation¶

Problem: opencode: command not found

Solution: The installation path is not in your $PATH.

macOS: Homebrew adds it automatically. If still not found, run:
```
eval "$(brew shellenv)"
```
Then try again.
Linux: If you installed from source, ensure /usr/local/bin is in your $PATH:
```
echo $PATH
```
If /usr/local/bin is missing, add it:
```
export PATH="/usr/local/bin:$PATH"
```
Windows (WSL): Ensure your WSL Linux distro is updated:
```
sudo apt-get update
```
Then retry the install.

Part B: Choose and Set Up a Model Provider¶

Pick one of the three options below. If unsure, choose Option B1 (Anthropic).

Option B1: Anthropic (Claude) — Recommended for Beginners¶

Step 1: Create an Anthropic Account¶

Go to https://console.anthropic.com/
Click "Sign Up" (or "Log In" if you already have an account)
Enter your email and set a password
Verify your email

Step 2: Add Billing¶

In the console, go to Billing (left sidebar)
Click Add Payment Method
Enter your credit card details
Anthropic will charge you only for what you use (no monthly subscription)

Typical costs: - Haiku (fast, cheap): ~$0.00025 per 1,000 input tokens, ~$0.001 per 1,000 output tokens - Sonnet (balanced, recommended): ~$0.003 per 1,000 input tokens, ~$0.015 per 1,000 output tokens - Opus (powerful, expensive): ~$0.015 per 1,000 input tokens, ~$0.075 per 1,000 output tokens

For this course, Sonnet is recommended. You will likely spend $20–30 total across all 10 weeks.

Step 3: Generate an API Key¶

In the console, go to API Keys (left sidebar)
Click Create Key
Give it a name like "OpenCode Course"
Click Create
Copy the key immediately — you will not see it again

The key looks like: sk-ant-v0-abc123def456...

Step 4: Store the API Key¶

On macOS/Linux:

Add this line to your shell profile (~/.zshrc, ~/.bashrc, or ~/.bash_profile):

export ANTHROPIC_API_KEY="sk-ant-v0-your-key-here"

Then reload your profile:

source ~/.zshrc

Or, for a one-off session, just set it:

export ANTHROPIC_API_KEY="sk-ant-v0-your-key-here"

On Windows (cmd.exe):

Set an environment variable:

setx ANTHROPIC_API_KEY "sk-ant-v0-your-key-here"

Then close and reopen your terminal.

On Windows (PowerShell):

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-v0-your-key-here", "User")

Then close and reopen PowerShell.

Step 5: Verify the Setup¶

Open a terminal and check:

echo $ANTHROPIC_API_KEY

You should see your key (or sk-ant-... in masked form). If you see nothing, the env var was not set correctly. Re-run the export/setx command above.

Option B2: OpenAI (GPT-4o)¶

If you prefer OpenAI:

Step 1: Create an OpenAI Account¶

Go to https://platform.openai.com/
Click "Sign Up" (or "Log In" if you have an account)
Complete the onboarding

Step 2: Add Billing¶

Go to Billing → Overview
Click Add to credit balance or add a payment method
Set a usage limit (recommended: $10/month for this course)

Typical costs for GPT-4o: - Input: ~$0.005 per 1,000 tokens - Output: ~$0.015 per 1,000 tokens

This is 2–3x more expensive than Sonnet, but GPT-4o is faster.

Step 3: Generate an API Key¶

Go to API Keys (left sidebar)
Click Create new secret key
Copy it immediately

The key looks like: sk-proj-abc123...

Step 4: Store the API Key¶

On macOS/Linux:

export OPENAI_API_KEY="sk-proj-your-key-here"

Add it to your shell profile for persistence:

echo 'export OPENAI_API_KEY="sk-proj-your-key-here"' >> ~/.zshrc
source ~/.zshrc

On Windows: Same as Anthropic, but use OPENAI_API_KEY instead.

Step 5: Verify¶

echo $OPENAI_API_KEY

Option B3: Local Ollama (Offline, Free)¶

If you cannot access cloud APIs, use Ollama.

Step 1: Install Ollama¶

macOS: Download from https://ollama.ai and run the installer
Linux:
```
curl https://ollama.ai/install.sh | sh
```
Windows: Download the installer from https://ollama.ai

Step 2: Download a Model¶

Start the Ollama daemon (if not already running):

ollama serve

(Leave this terminal open.)

In a new terminal, download a model:

ollama pull mistral

Or, for a smaller model (faster, less capable):

ollama pull neural-chat

This downloads the model to your machine (~5–10 GB depending on the model).

Step 3: Verify Ollama is Running¶

curl http://localhost:11434/api/tags

You should see a JSON response listing your downloaded models.

Step 4: Configure OpenCode to Use Ollama¶

Create or edit ~/.opencode/opencode.jsonc:

{
  "models": {
    "default": {
      "provider": "ollama",
      "model": "mistral"
    }
  }
}

No API key needed! OpenCode will connect to http://localhost:11434.

Part C: Your First Task¶

Setup: Clone the Sample Project¶

We have a tiny Node.js project with a typo. Clone it:

git clone https://github.com/opencode/course-sample-typo.git ~/typo-sample
cd ~/typo-sample

If the URL doesn't work, create a simple project:

mkdir ~/typo-sample
cd ~/typo-sample
git init

Create src/index.js:

// This file has a typo
consoel.log("Hello, World!");

function greet(name) {
  consoel.log("Welcome, " + name);
}

module.exports = greet;

Task: Fix the Typo¶

Step 1: Start OpenCode¶

opencode

You should see the OpenCode TUI with an input box at the bottom.

Step 2: Use Plan Mode (Read-Only Exploration)¶

Type this prompt:

Find the typo in src/index.js and tell me what needs to be fixed.

Press Enter.

The agent (in plan mode) will read the file and identify the typo: consoel should be console.

Step 3: Switch to Build Mode¶

Press Tab to switch from plan mode to build mode. You should see the mode indicator flip to [build | plan].

Step 4: Fix the Typo¶

Type:

Fix the typo in src/index.js. Replace consoel with console.

Press Enter.

The agent (in build mode) will edit the file and confirm the change.

Step 5: Verify the Fix¶

OpenCode will print something like:

[Edited src/index.js]
✓ File updated.

Exit OpenCode (press Ctrl+C or type exit).

Run this in your terminal:

grep console.log src/index.js

You should see:

console.log("Hello, World!");
console.log("Welcome, " + name);

Not:

consoel.log(...)

Congratulations! You have completed your first task with OpenCode.

Part D: Reflection¶

Answer these questions (no more than 5 minutes):

What was the first thing OpenCode did when you asked it to find the typo?
Did it find the right file? Why or why not?
In plan mode, could the agent edit the file? How did you know?
What changed when you switched to build mode?
Did the agent ask for your approval before editing? Should it have?

Write your answers and keep them for the reflection exercise in Lab 2.2.

Troubleshooting¶

Issue	Solution
`opencode: command not found`	Check Part A. Your `$PATH` is missing the opencode binary.
`Error: No API key found`	Check Part B. Ensure `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` is set. Run `echo $YOURKEY` to verify.
`Connection refused: http://localhost:11434`	(Ollama users) Ensure `ollama serve` is running in another terminal.
`Agent says "I cannot edit files"`	You are in plan mode. Press `Tab` to switch to build mode.
`Permission denied`	(Linux/macOS) The opencode binary needs execute permission. Run `chmod +x /usr/local/bin/opencode`.

What's Next?¶

Lab 2.2 will have you run /init on a real open-source project and interpret the generated AGENTS.md.
After that, Week 3 teaches you how to use plan mode effectively for exploration and code review.

You're done with Lab 2.1! Move on to Lab 2.2.