Drive a Local LLM From Your Terminal With OpenCode and LM Studio

If you have ever wished your AI coding assistant lived in the same terminal where you actually do your work, this is the setup for you. We will wire OpenCode, an open source terminal AI agent, to a self hosted LM Studio server. Once it is running, every refactor, file edit, and shell command is answered by a model running on your own GPU.

The walkthrough takes about 15 minutes. The last 5 of those will probably be spent on a single, frustrating gotcha that everyone hits the first time. We will cover that one explicitly so you don't have to discover it the hard way.

What You Get

A terminal AI assistant that runs locally with full filesystem and shell access
One config file that pins your provider, your endpoint, and your model list
Zero API spend, your hardware, your bandwidth, your latency floor
Drop in support for any OpenAI compatible server, not just LM Studio: Ollama, llama.cpp, vLLM, text generation webui, you name it

What You Will Need

A machine running LM Studio with at least one chat model downloaded. For this walkthrough I will assume it is reachable at 10.0.0.50:1234 on your LAN. Substitute whatever IP yours is on.
A workstation where you want OpenCode to run, your laptop, a dev VM, a remote box you SSH into.
5 minutes of patience for the gotcha section.

The Architecture in One Picture

Your workstation runs OpenCode and speaks the OpenAI Chat Completions protocol over HTTP to LM Studio at 10.0.0.50:1234. LM Studio serves one or more loaded GGUF models and streams tokens back. Everything else is plumbing.

Step 1 — Turn On LM Studio's Server

Open LM Studio, go to the Developer or Local Server tab, and toggle Status: Running. Note the URL it shows. Usually it is http://localhost:1234 for local only, or http://<your-LAN-ip>:1234 for network access. To make it reachable from another machine, enable Serve on Local Network.

Load at least one model from the Loaded Models list. Crucial detail: a model has to be both downloaded and loaded to serve requests. The /v1/models endpoint will list everything downloaded; only loaded ones actually answer.

Verify from any other machine by hitting http://10.0.0.50:1234/v1/models and you should see a JSON list of model IDs. Write these IDs down. They are the only names LM Studio recognizes. This will matter in 90 seconds.

Step 2 — Install OpenCode

On macOS or Linux, run the official installer from opencode.ai/install via shell. It drops a binary at ~/.opencode/bin/opencode and adds it to your shell rc. Open a new shell and check opencode --version.

Step 3 — Configure the Provider

OpenCode reads its main config from ~/.config/opencode/opencode.json. Create it if it does not exist. Use this template:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lmsrv": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://10.0.0.50:1234/v1"
      },
      "models": {
        "qwen3-30b-a3b-instruct": { "name": "Qwen3 30B Instruct" },
        "google/gemma-3-12b-it": { "name": "Gemma 3 12B" }
      }
    }
  }
}

Three things to notice and one to actively avoid:

The provider key lmsrv is the internal provider ID. Use any unique name except lmstudio. Why? Read the next section.
The name field is the display label shown in OpenCode's model picker.
The options.baseURL must end in /v1. LM Studio appends /chat/completions to whatever you give it.
The models keys are the exact local IDs from the /v1/models listing. The name field is just the display label.

Step 4 — Restart OpenCode and Pick a Model

Start opencode in a project folder. Run /models. You will see your provider "LM Studio (local)" with each model listed. Pick one. Type a prompt. Watch tokens stream from your own hardware.

If it works, congrats, you are done. If you get an error, the next section is for you, and trust me, you are not alone.

The Gotcha That Eats Afternoons: Invalid Model Identifier

This is the error nine out of ten people hit on the first run. Something like:

Invalid model identifier vendor/model-name. Please specify a valid downloaded model.

The error message has the answer in it. LM Studio is rejecting vendor/model-name because that is the canonical or upstream name. LM Studio only knows the local filename it shipped under, which is often something with the quantization scheme appended.

Why does OpenCode send the wrong name?

OpenCode ships with a built in catalog of known models for known providers. The provider key lmstudio is one of them, and its catalog contains canonical names that don't match the filenames LM Studio actually serves. If you let OpenCode auto configure, for example via the /connect slash command, it activates that built in lmstudio catalog and the model picker shows canonical names that LM Studio cannot resolve.

The Fix

We sidestep the collision in three small moves.

One. Use a unique provider key in your config: lmsrv, lms, mybox, anything that is not lmstudio. The example above uses lmsrv. This guarantees no merge with the built in catalog.

Two. If you ran /connect earlier, rename the auth file it created. The /connect flow tends to write the URL into what should be the API key field, and that is enough to keep the built in catalog active. LM Studio does not need an API key, so the file should not be there at all. The path is ~/.local/share/opencode/auth.json. Rename it to auth.json.bak so OpenCode no longer sees it.

Three. Reset the cached model selection so OpenCode does not try to send the old broken ID on launch. The path is ~/.local/state/opencode/model.json. Rename it to model.json.bak.

Quit OpenCode with /exit, restart, and run /models again. Only your custom entries appear. Pick one, send a hello, watch it work.

Other Things That Might Bite

"It says the model is loaded but I get a 404"

Double check: in LM Studio's Loaded Models list, does the model show READY in green, or is it queued or loading? Models above 10 GB take a minute on slower disks.

"It worked yesterday and now it doesn't"

Usually one of:

LM Studio restarted and your model unloaded
You updated LM Studio and it changed the Served Model Identifier for one of your loaded models. Check the Developer tab, click the loaded model, find the identifier field.
You filled VRAM trying to load a second model. The new one silently fails and the old one is still serving stale name. A quick check of /v1/models is always the first diagnostic. If the ID you are sending is not in that list, that is your problem.

Different temperature or context length per model

OpenCode passes through provider specific options inside the model entry under an options.body block. The body block is merged into the JSON body of the chat completions request. Setting enable_thinking: false is especially handy for Qwen models that emit a thinking block that OpenCode does not render well today.

Running OpenCode on a different machine than LM Studio

Yes, that is the whole point of the network accessible LM Studio server. The OpenCode workstation can be your laptop while LM Studio runs on a dedicated GPU box. Set the LM Studio server to Serve on Local Network, point baseURL at the GPU box's LAN IP, and you are done.

What about other OpenAI compatible servers?

Swap the baseURL to whatever your server uses:

Ollama: http://localhost:11434/v1
vLLM: http://your-host:8000/v1
llama.cpp server: http://your-host:8080/v1
text generation webui: http://your-host:5000/v1 The models keys are still whatever each server reports under /v1/models.

Why I Bother

Two reasons. First, when I am working on something sensitive, a half written paper, a customer's repo under NDA, a side project I have not open sourced yet, I genuinely don't want it traversing the public internet on its way to a model. Local first is the correct default.

Second, owning the loop changes how I work with LLMs. When you can swap from a 30B reasoning model to a fast 7B sketch model with one keystroke, you start treating models as a tool you reach for, not a service you consult. The work feels more like editing in vim than messaging a chatbot.

Recap

LM Studio serves OpenAI compatible endpoints; OpenCode talks to them.
Define your provider in ~/.config/opencode/opencode.json with a unique provider key and explicit model IDs.
If the wrong model ID is being sent, the cause is almost always the built in lmstudio catalog being merged into yours. Rename your provider key, drop auth.json, reset model.json.
Same recipe works for Ollama, vLLM, llama.cpp, anything that speaks the OpenAI Chat Completions protocol. May your tokens always be local.