Lab 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 a free OpenCode Zen account and get your API key. 3. Connect OpenCode to a free Zen model. 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: Connect OpenCode to a Free Zen Model¶

OpenCode Zen gives you free, tested models for coding agents. No credit card required.

Step 1: Create an OpenCode Zen Account¶

Go to opencode.ai/auth
Click "Sign Up" (or "Log In" if you already have an account)
Enter your email and verify it

Step 2: Get Your API Key¶

In the Zen dashboard, look for API Keys or Settings
Click Create Key (or copy the existing key)
Copy the key immediately — you will not see it again

The key looks like a random string of letters and numbers.

Step 3: Connect OpenCode¶

Start OpenCode:

opencode

In the OpenCode TUI:

Type /connect and press Enter
Select OpenCode Zen from the list
Paste your API key when prompted
Press Enter

You should see a confirmation message like "Connected to OpenCode Zen."

Step 4: Pick a Free Model¶

Run:

/models

You'll see a list of available models. Free models are marked as such. Pick one of these free options:

Model	Description
`opencode/big-pickle`	General purpose, good for learning
`opencode/minimax-m2.5-free`	Fast responses
`opencode/gpt-5-nano`	Lightweight, good for simple tasks

To select a model, type:

/model opencode/big-pickle

Step 5: Verify Everything Works¶

Send a simple prompt:

Say hello

If the agent responds, you're connected. If you see an error about "no model selected" or "invalid key," re-run /connect and double-check your API key.

Optional: Upgrade to OpenCode Go¶

If you want more powerful models later:

Go to opencode.ai/go
Subscribe ($5 first month, then $10/month)
Run /models again — Go models now appear in the list
Select a premium model like opencode-go/kimi-k2.6

You can switch between free and premium models anytime with /models.

Part C: Your First Task¶

Setup: Clone the Sample Project¶

We have a tiny Node.js project with a typo. From your course repo root, copy it into your disposable lab workspace:

mkdir -p ~/opencode-labs
cp -R labs/module-02-typo-sample ~/opencode-labs/module-02-typo-sample
cd ~/opencode-labs/module-02-typo-sample

If you prefer, you can also create a simple project manually:

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.

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. Run `/connect` in OpenCode, select Zen, and paste your API key.
`Model not available`	Run `/models` to see free options. Try `opencode/big-pickle` or `opencode/gpt-5-nano`.
`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 will have you run /init on a real open-source project and interpret the generated AGENTS.md.
After that, module 3 teaches you how to use plan mode effectively for exploration and code review.

You're done with Lab 1! Move on to Lab 2.