Get your key: what an API, a model, and a provider are

OpenCode is the tool, but it doesn't come with a model inside: it connects to one running in the cloud. To connect it you need a key (API key) from a model provider. In this lesson you first understand what those pieces are and why they work this way; then you choose a provider, create your account, and save your key. The hands-on part takes about 5 minutes.

A fair warning: these steps are about real websites, and websites change. This guide is from September 2026. If a button has a different name, the logic is the same.

Four concepts, in plain words

What a model is

A language model (or just model) is the AI itself: a huge program, trained on an enormous amount of text, that takes text in and produces text out. You give it a question or a job, and it answers. It's the "brain" OpenCode consults every time it has to decide what to do.

Good models are so large they don't fit comfortably on a regular laptop. That's why they run on powerful computers owned by other companies, in the cloud.

What a provider is

A model provider is the company that has those models running on its servers and lets you use them over the internet. Some providers build their own models; others, like OpenRouter, are an intermediary that gives you access to models from many companies with a single account.

What an API is

An API (application programming interface) is the way one program asks another program for something. Think of a restaurant:

• You (OpenCode) are at the table.
• The kitchen (the model) cooks the food, but you don't walk into the kitchen.
• The waiter (the API) takes your order in a clear format, brings it to the kitchen, and comes back with your plate.

You don't need to know how the kitchen works. You just need to order in a way the waiter understands. OpenCode already knows how to talk to many providers' APIs; you just give it the key.

What a key (API key) is and why it's secret

An API key is a secret string of text that tells the provider who is asking. Sticking with the restaurant, it's like your customer account number: the waiter writes it on every order, and everything ordered with it is charged to your name.

That's why it's secret. Whoever has your key can place orders as if they were you: use up your free limit or, if you ever add a card, spend your money. You don't lend it, you don't paste it in a chat, and you don't show it on screen.

How a request travels

Every time OpenCode needs the model to think, it puts together a request: a package with your job, the content it has read from your files, and your key. Here's what happens:

  YOUR LAPTOP                             THE CLOUD
+--------------+                  +-----------------------------------+
|              |  1. request      |  Provider                         |
|   OpenCode   |  (job +          |  (OpenRouter, Zen, or Groq)       |
|              |   files +        |                                   |
|              |   your key)      |  2. Checks the key:               |
|              | ---------------> |     is it valid? any limit left?  |
|              |                  |            |                      |
|              |                  |            v                      |
|              |                  |  3. Hands it to the model         |
|              |                  |     +-----------------------+     |
|              |                  |     |  Model: reads, thinks |     |
|              |                  |     +-----------------------+     |
|              |  4. answer       |            |                      |
|              | <--------------- |  <---------+                      |
+--------------+                  +-----------------------------------+

If the key was pasted wrong, step 2 fails and you see an authentication error. If you've used up your limit, step 2 also stops you, with a rate limit error. Those are the two most common errors, and now you know where they come from.

Why an agent makes several requests per job

A chat makes one request for each of your messages. An agent makes several, because it works in a loop: it thinks, uses a tool, looks at the result, and thinks again. Every time it "thinks again," that's a new request to the model.

  Your job: "Add up the expenses in expenses.csv"

  request 1 --> model: "First I need to read expenses.csv"
                OpenCode reads the file on your laptop
  request 2 --> model: "I read it. I'll total by category and answer"
                OpenCode shows you the answer

  A simple job = 2 requests or more.
  A job that reads 3 files and writes 1 = 5 requests or more.

That's why free plans count requests and not messages: it costs them every time the model works.

Choose your provider

There are two cloud paths that work well for the workshop, and both give you free models. Further down there's a third one, path C, to run the model on your own laptop with LM Studio.

If you don't want to give any payment details, use OpenRouter. It's the path we follow live.

About the 50-requests-per-day limit: with what you just saw, one job can use 2 to 5 requests or more. So 50 is enough for the session and some practice, not for working all day. And the 20-per-minute limit explains why the agent sometimes pauses for a moment if you ask for many things in a row. If you run out one day, it's not an error: it's the free plan doing its job.

Path A: OpenRouter

1. Go to openrouter.ai and create an account (you can use Google or GitHub).
2. In your account menu, go to Keys.
3. Create a new key (Create Key) and give it a name you'll recognize, for example agent-workshop. The name is just for you: it tells you which key to delete if it ever leaks.
4. Copy it and save it right then. The full key is only shown once. If you close the window without copying it, you'll have to create another one: no big deal, but you save yourself the step.

The key looks roughly like this: sk-or-v1-xxxxxxxxxxxx. That sk-or-v1- prefix is normal, and it lets you recognize an OpenRouter key at a glance.

Path B: OpenCode Zen

1. Go to opencode.ai/auth and sign in.
2. Add your billing details. Models marked as free cost 0 and generate no charge; Zen only asks for the details to give you the key.
3. Copy your key and save it.

Path C: a local model with LM Studio (no key, no internet)

So far, the model lives on a provider's servers. There's another option: download a model and run it on your own computer. LM Studio is a free app that does exactly that: it downloads the model, loads it into your laptop's memory, and serves it through an API that works like a provider's, but on your machine. OpenCode can't tell the difference: you talk to the same "waiter" as always, only the kitchen is in your house.

Paths A and B (in the cloud)              Path C (local)

  OpenCode ──internet──► provider          OpenCode ──► LM Studio
     ▲                   (uses your key)      ▲         (on your laptop)
     │                        │               │              │
     └──────── answer ◄───────┘               └──── answer ◄─┘

  Your files travel to the provider        Your files never leave your laptop

When to choose it: if you have a Mac with an M chip (M1 or newer) or a PC with 16 GB of RAM or more, and you want to work with no key, no limits, and without your files leaving your computer. When not to: if your laptop has 8 GB of RAM, or if you're installing it at the last minute. The download is several GB: do it before the session, not during it. If in doubt, use OpenRouter live and try LM Studio calmly afterwards: what you learn in the workshop works the same with both.

Step by step

1. Download LM Studio from lmstudio.ai and install it like any other app.
2. Open it, go to the model search and look for qwen3-8b. Download qwen/qwen3-8b. It's a model trained to use tools, which is exactly what an agent needs.
3. Load the model and, while loading it, find the Context Length option and raise it to 16384 or more. The context is the model's desk: if it's too small, OpenCode's instructions plus your files don't fit, and the agent fails at using tools.
4. Go to the Developer tab and turn on Start server. From then on LM Studio answers at http://127.0.0.1:1234, an address that only exists inside your computer.

If you prefer the terminal, LM Studio ships the lms command, which does steps 3 and 4:

lms load qwen/qwen3-8b --context-length 16384
lms server start

Tell OpenCode where your model is

OpenCode doesn't look for LM Studio by itself: you tell it in opencode.json. These blocks rewrite the opencode.json in your practice folder: they keep the same permissions as before (ask) and add LM Studio as a provider. Paste the one for your system into the terminal.

Mac and Linux:

cd ~/agent-workshop
cat > opencode.json <<'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "qwen/qwen3-8b": {
          "name": "Qwen3 8B (local)"
        }
      }
    }
  }
}
EOF

Windows (PowerShell):

Set-Location "$HOME\agent-workshop"
@'
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "qwen/qwen3-8b": {
          "name": "Qwen3 8B (local)"
        }
      }
    }
  }
}
'@ | Set-Content -Encoding ascii opencode.json

What each new part means:

In the session, on this path you don't need /connect: there's no key. Just open OpenCode, type /models and choose Qwen3 8B (local). LM Studio has to be open with the server on.

A note on privacy

This applies to paths A and B; with path C your files never leave your laptop. Remember the diagram: every request carries your job and the content of the files the agent read. Several free models use what you send them for training: that's how you "pay" for the free plan. For the workshop we work with sample data, so it doesn't matter. As a general rule, don't give a free model personal data or information from your job.

Plan B, in case your provider fails

Every account is its own world. If neither of the two works for you, Groq (console.groq.com) also has a free tier: account, API Keys, Create API Key, copy. OpenCode connects to Groq the same way as to the other two. That's the advantage of OpenCode not coming with a model inside: you can switch providers without switching tools.

Store your key carefully

• Save it in a password manager or a private note.
• Don't paste it in the video call chat or show it on screen.
• If it ever leaks, go to the provider, delete it, and create another one. It's free and takes a minute. Once deleted, it stops working for anyone who has it.

During the session you paste it only once into OpenCode, with the /connect command. OpenCode stores it on your computer and adds it to every request on its own.

Check that you're ready

• I have an account on OpenRouter (or OpenCode Zen, or Groq).
• I created a key and saved it somewhere I can find it.
• (Path C only) LM Studio has qwen/qwen3-8b downloaded, the server starts, and my opencode.json already includes lmstudio.

Check your understanding

Summary

• The model is the AI; the provider has it on its servers; the API is how you ask it for things; your key identifies you on every request, and that's why it's secret.
• An agent makes several requests per job, which is why free plans count requests. OpenRouter gives you :free models with no card, at 20 requests per minute and 50 per day. OpenCode Zen also has free models, but it asks for billing details. Groq is plan B.
• LM Studio runs a model on your own laptop: no key, no limits, and your files never leave it, in exchange for a download of several GB, a laptop with good memory, and a less capable model. You set it up before the session.
• With your key saved, you're ready for the session.

Resources

• OpenRouter: usage limits
• OpenCode: providers, including LM Studio
• LM Studio
• OpenCode Zen
• OpenCode: providers