Connecting OpenCode to the University OpenWebUI

Four steps, about 15 minutes. Afterwards OpenCode runs with the university model in every project – set up once, not per folder.

You need: one terminal command, the included file opencode.json, and your university key. No script, no hidden directory, no form inside the app – and the same command works in every folder afterwards.

At a glance

Why not the desktop app?

The desktop app is the comfortable surface – but it does not create a terminal command (the „Install CLI…“ menu item exists on macOS only). After installing the desktop app, typing opencode in a terminal gets you „command not found“. Since the terminal is where the real working mode lives (you see the agent read files and run commands there), we set up the terminal version directly. The desktop app can be added later as an option – it shows the same sessions.

Step 0: Terminals, once and for all (3 minutes)

Everything below happens in a terminal – a window where you give the computer commands by typing text. No chat, no search bar: you type a line, press Enter, the computer answers in text. The agent will later work visibly in this window, which is why the small detour is worth it.

Opening a terminal:

How it differs from Word & co: there is nothing to click. A cursor blinks after C:\Users\YourName> (Windows) or yourname@macbook ~ % (macOS) and waits for a line of text. That is where you type everything below.

How it differs from a chat: you are talking to the operating system, not to a model. node --version is not a question for an AI – it is a command to the system.

Step 1: Check reachability (1 minute)

Open https://openwebui.uni-freiburg.de in your browser.

The instance is reachable only from the university network. eduroam alone is not enough. VPN: download FortiClient from rz.uni-freiburg.de (Services → Netz & Telefon → VPN), create an SSL VPN connection with server fortivpn.uni-freiburg.de, username <Uni-Account>@uni-freiburg.de, password = your eduroam password.

Step 2: Get the key (2 minutes)

1. In OpenWebUI, click the profile icon at the bottom left.
2. Open Settings → Account (German: Einstellungen → Konto).
3. Scroll to the API keys section (German: API-Schlüssel) and click Show next to Secrets (German: Zugangsdaten → Anzeigen – the section is collapsed).
4. Click Create new secret key, then Copy API Key.

Exactly one key per account. A second click on Create new secret key invalidates the first – anything using it is rejected from that moment. The key can be displayed again at any time; it does not have to be renewed.

Step 3: Install OpenCode (10 minutes, usually less)

3a. Install Node.js (if not present):

1. Open nodejs.org in your browser – there is one big green button, „LTS“ (Long Term Support; the stable variant). Click it, the installer downloads (Windows: .msi, macOS: .pkg).
2. Double-click the downloaded file and click through the installer – the default settings are fine, change nothing. Windows may ask for admin rights: allow, that is normal program installation.
3. Then open a new terminal window (important: a window that is already open does not know the freshly installed program yet) and check:

node --version

A version number (e.g. v22.x.x) means you are ready.

3b. Install OpenCode – in the terminal:

npm install -g @opencode/cli

Then check – in any folder you like, the command works machine-wide:

opencode --version

A version number means the command is available everywhere: in Documents, on the Desktop, in every project folder. That is the PATH – a global command list that npm registers the command in.

Step 4: One file in your home folder (2 minutes)

The file opencode.json can be downloaded directly here: opencode.json – right-click and „Save as" (do not open it in the browser). It belongs in your home folder – the folder that opens when you start your file manager:

1. Copy opencode.json there.
2. Open the file in a text editor (Windows: Notepad; macOS: TextEdit – use „Format → Make Plain Text").
3. Insert the key from step 2: replace the placeholder PASTE_YOUR_KEY_HERE, keeping the quotes around it.
4. Save.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openwebui/standard-coding-ufr",
  "provider": {
    "openwebui": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Uni Freiburg",
      "options": {
        "baseURL": "https://openwebui.uni-freiburg.de/api/v1",
        "apiKey": "PASTE_YOUR_KEY_HERE"
      },
      "models": {
        "standard-coding-ufr": { "name": "Coding" },
        "standard-chat-ufr":   { "name": "Chat" },
        "ufr/coding-complex":  { "name": "Coding Complex",
                                 "limit": { "context": 1048576, "output": 32000 } },
        "gemma-4-31b-llmlb":   { "name": "Gemma 4 31B" }
      }
    }
  }
}

Why the home folder? OpenCode searches for the file from the working folder upwards to your home folder. A file there therefore applies to every project below it – documents, desktop, everything – without anything sitting inside a project. And it is visible: no directory you have to reveal first.

One special case: if you work in a project outside your home folder (external drive, network share), copy the same file into that project folder as well. Nothing else to do.

Step 5: Test (1 minute)

Open a terminal, start opencode in any project folder and write:

Say hello in one sentence and name your model.

The model „Uni Freiburg → Coding" is preselected by the file. If it answers, setup is done – in every project, with no further step.

The desktop app (optional): if you want the graphical surface alongside, download it from opencode.ai/download. It reads the same configuration and shows the same sessions – no second setup needed.

If something does not work

Three things worth knowing

• One key, two tools. The same university key works in Hermes and in OpenCode. Anyone setting up both stores it twice but does not create a second key – a new key invalidates the old one in both tools.
• The key sits in plain text in the file. That is acceptable for a file in your home folder: it is in no git repository and in no cloud folder. Never pass the file on without removing the key first. If a key goes astray: create a new one, the old one is invalid immediately.
• Thinking models. OpenCode separates reasoning and answer itself; nothing to do here. Only your own scripts need a generous max_tokens.