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.

Looking for the bigger picture?

Getting Started with AI covers this setup plus everything around it — choosing a tool, the Voyager config generator, agents, the RC skills library, and the prompting habits that make locally hosted models work well. This page is the detailed OpenCode reference.

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 muse-glimmer-30b). You will use it in the provider config below. Choose one with the Tools badge — without tool calling, OpenCode cannot edit files.

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.

Open your shell's startup file in a text editor 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:

nano ~/.zshrc     # macOS; use ~/.bashrc on most Linux systems

Add this line at the bottom, pasting your key between the quotes, then save and exit (Ctrl+O, Enter, Ctrl+X in nano):

export OPENAI_API_KEY="paste-your-key-here"

Editing the file, rather than echoing the line into it, keeps the key out of your shell history.

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, screenshots, and your shell history

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.

Bear in mind that anything you type at a prompt is written to your shell history in plain text — ~/.zsh_history, ~/.bash_history, or PowerShell's ConsoleHost_history.txt. Keep the key out of commands as well as files. If it ends up somewhere it should not, regenerate it in the portal; rotating a key invalidates the exposed one.

5. Add the RC gateway as a provider​

OpenCode reads its settings from ~/.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.

Let Voyager generate this file

The Voyager portal → LLM Access → opencode tab builds this file for you, with the endpoint and your real model list already filled in — plus agent roles and tool permissions. Choose Environment variable for the API key so your secret stays out of the file, then copy or download it to the path above. The walkthrough is in Getting Started with AI. The manual version below is here so you understand what the generator produces.

To write it by hand, 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": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ASU Air",
      "options": {
        "baseURL": "https://openai.rc.asu.edu/v1",
        "apiKey": "{env:OPENAI_API_KEY}"
      },
      "models": {
        "muse-glimmer-30b": { "name": "muse-glimmer-30b" },
        "devstral2-123b": { "name": "devstral2-123b" }
      }
    }
  },
  "model": "asu/muse-glimmer-30b"
}

What each part does:

  • provider.asu — the short ID for this provider. Agents and the model field reference models as asu/model-id, so if you change this key you must change those references too. The Voyager generator uses asu.
  • name — the display label in the model picker. The generator uses "ASU Air".
  • 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. Pick at least one with the Tools badge, or OpenCode will not be able to edit files.
  • 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. Click Default Project to open the projects menu and make a new one instead, at the directory of your choosing.
  3. Open the model picker and choose a model under ASU Air. Make sure you pick one with the Tools badge, or OpenCode will not be able to edit files.
  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 Air 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 Air.

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.