Skip to main content

Set Up OpenCode with the RC LLM API

Level: Beginner · Time: 15–20 min · Category: How-to

Tags: OpenCode · AI coding assistant · Custom Provider

OpenCode is a free AI coding assistant. You describe what you want in plain English, and it reads your project, writes and edits files, and runs commands for you. This guide connects OpenCode to the Research Computing LLM gateway so it uses your RC API key and the models available to your account.

This page assumes no prior setup. If a step already applies to you, skip it.

New to this? What is an "AI coding assistant"?

An AI coding assistant is a program that talks to a large language model (LLM) and can act on your project — creating files, editing code, and running commands — based on instructions you type in plain language. OpenCode is one such assistant. It does not include a model of its own; you point it at a model provider. Here, that provider is the Research Computing LLM gateway.

What you will do​

  • Get your RC API key and a model ID from the portal.
  • Install OpenCode.
  • Store your API key as an environment variable so it stays out of your files.
  • Add the RC gateway as a provider so OpenCode knows the endpoint and models.
  • Open OpenCode (desktop app or terminal), select an RC model, and send a test message.

1. Get your API key and a model ID​

OpenCode needs two values from the portal before anything else.

  1. Follow the LLM API Guide to create an API key.
  2. On the same page, open the model list and copy one model ID available to your account (for example llama4-scout-17b). You will use it in the provider config below.

Keep the key somewhere safe for the next step. Treat it like a password — never paste it into shared files, screenshots, or Git.

2. Install OpenCode​

Pick your operating system. The curl and package-manager installers below do not require Node.js.

The one-line installer works on both:

curl -fsSL https://opencode.ai/install | bash

Or, if you use a package manager:

# macOS (Homebrew)
brew install anomalyco/tap/opencode

# Arch Linux
sudo pacman -S opencode

Confirm it installed. This should print a version number:

opencode --version
If "opencode" is not found

Fully quit and reopen your terminal so it picks up the newly installed command, then run opencode --version again. Prefer to install with npm instead? Run npm install -g opencode-ai — but that route needs Node.js, so set up Node.js first.

3. Understand the two pieces you are about to set up​

Connecting OpenCode to RC takes two pieces that work together — not one or the other:

  1. A provider config — a small JSON file that tells OpenCode where the RC gateway is (https://openai.rc.asu.edu/v1) and which models exist. Without it, OpenCode has no idea RC exists.
  2. Your API key — the secret that proves the request is yours. The config file references the key from an environment variable so your secret never sits inside the file itself.

You need both. The next two steps set up one each.

4. Store your API key as an environment variable​

An environment variable is a named value your shell hands to every program it launches. Storing the key here keeps it out of your project files.

Add the export line to your shell's startup file so it is set every time you open a terminal — use ~/.zshrc on macOS (the default shell is zsh) or ~/.bashrc on most Linux systems:

# Append the line to your shell startup file (macOS shown; use ~/.bashrc on Linux)
echo 'export OPENAI_API_KEY="paste-your-key-here"' >> ~/.zshrc

Now source the file. Sourcing re-reads it into your current terminal, so you do not have to close and reopen it:

source ~/.zshrc
What does "source" mean, and why do I need it?

Your shell only reads ~/.zshrc (or ~/.bashrc) once, when a terminal first opens. Editing the file afterward does not change terminals that are already open. source ~/.zshrc re-runs the file in your current terminal so the new export takes effect immediately. New terminals you open later pick it up automatically.

Confirm it is set (this should print your key):

echo $OPENAI_API_KEY
Keep the key out of Git and screenshots

Because the key lives in an environment variable, it never needs to appear in your project. Do not paste it into code, commit it, or share a screenshot that shows it.

5. Add the RC gateway as a provider​

Create OpenCode's config file at ~/.config/opencode/opencode.json (macOS/Linux) or %USERPROFILE%\.config\opencode\opencode.json (Windows). This is the global config, so RC is available in every project. Paste the following and replace the model IDs with real ones from your voyager model list:

~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "asu-rc": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ASU Research Computing",
      "options": {
        "baseURL": "https://openai.rc.asu.edu/v1",
        "apiKey": "{env:OPENAI_API_KEY}"
      },
      "models": {
        "llama4-scout-17b": { "name": "Llama 4 Scout 17B" },
        "qwen3-72b": { "name": "Qwen3 72B" }
      }
    }
  },
  "model": "asu-rc/llama4-scout-17b"
}

What each part does:

  • provider.asu-rc — a short ID you choose for this provider. It appears in the model picker as the display name, "ASU Research Computing".
  • npm: "@ai-sdk/openai-compatible" — the adapter for any OpenAI-compatible gateway like RC. Leave this exactly as shown.
  • options.baseURL — the RC gateway endpoint. Already correct; do not change it.
  • options.apiKey: "{env:OPENAI_API_KEY}" — reads the key from the environment variable you set in step 4. The {env:...} syntax keeps the secret out of this file.
  • models — the model IDs your key can use. Each key must match a model ID from the portal exactly; the name is just a friendly label. Add or remove entries to match your account.
  • model — the default model, written as provider-id/model-id. Optional, but it saves you from picking one every time.
Creating the folder

If the ~/.config/opencode/ folder does not exist yet, create it first: mkdir -p ~/.config/opencode (macOS/Linux). Then create opencode.json inside it with the content above.

6. Open OpenCode and select an RC model​

OpenCode has two interfaces that use the same config and key you just set up. Use whichever you prefer — they are fully equivalent for this tutorial.

The desktop app is the most approachable if you are new to the terminal.

  1. Install the OpenCode desktop app from opencode.ai and open it.
  2. Open a project folder when it asks (any folder is fine for a first test — even an empty one).
  3. Open the model picker and choose a model under ASU Research Computing.
  4. Type a message in the chat box and send it (see step 7).
If the RC provider or an RC model is missing

The app reads the same ~/.config/opencode/opencode.json from step 5 — make sure you saved it, then fully quit and reopen the app so it reloads the config. If a model returns an authentication error, the app may not see your shell's environment variable; in that case run opencode auth login once in a terminal, choose the ASU Research Computing provider, and paste your key. That stores the key in OpenCode's own auth store, which both interfaces can use.

7. Send a test message​

With an RC model selected, send a harmless prompt to confirm the whole chain works:

Reply with exactly: OpenCode is connected to ASU Research Computing.

A normal reply — with no authentication, provider, or model-not-found error — means OpenCode is talking to the RC gateway with your key. You are ready to build.

A good next prompt, once connected:

Look at the files in this folder and summarize what this project does. Do not edit anything yet.

Troubleshooting​

  • opencode: command not found — quit and reopen your terminal after installing. If you installed via npm, confirm Node.js is set up (node --version).
  • Authentication failed / 401 — your key is wrong, expired, or not visible to OpenCode. Confirm echo $OPENAI_API_KEY (macOS/Linux) or echo $env:OPENAI_API_KEY (Windows) prints your key, then restart OpenCode. In the desktop app, use opencode auth login as described in step 6.
  • No RC provider or models in the picker — the config was not loaded. Re-check the path and JSON in step 5, then fully restart OpenCode (config changes need a restart).
  • Model not found — a model ID in opencode.json does not match the portal. Copy the exact ID from the model list and update the models block.
  • Key works in curl but not OpenCode — the environment variable is not set in the session that launched OpenCode. Re-run step 4, source your shell file, and start OpenCode from that same terminal. For the desktop app, prefer opencode auth login.