LM Studio, Ollama, vLLM, llama.cpp, a machine on your LAN, or a GPU box over Tailscale.
No hand-written model lists. No API keys copied into config files. No fighting stale setup.
OpenCode works beautifully with built-in providers. Local models are a little messier.
You load a different model in LM Studio. You restart Ollama. You move vLLM to another machine. The model name changes, but your OpenCode configuration does not.
OpenCode Local Setup keeps the two in sync.
When you open OpenCode, it checks the model servers you configured, discovers what is actually available, and updates only the relevant part of your opencode.json.
Your model server → discovers live models → OpenCode is ready
It leaves the rest of your OpenCode setup alone.
curl -fsSL https://opencode.ai/install | bashgit clone https://github.com/groxaxo/opencode-local-setup.git
cd opencode-local-setup
./scripts/install.shopencodeThat is it. The default setup looks for LM Studio at:
http://127.0.0.1:1234/v1
Inside OpenCode, use /models to choose a model.
Note
This project connects OpenCode to your model server. It does not install LM Studio, Ollama, vLLM, llama.cpp, or the models themselves.
| You run | Start with | Helper command |
|---|---|---|
| LM Studio | http://127.0.0.1:1234/v1 |
oc-lmstudio |
| Ollama | http://127.0.0.1:11434/v1 |
oc-ollama |
| vLLM | http://127.0.0.1:8000/v1 |
oc-vllm |
| llama.cpp | http://127.0.0.1:8080/v1 |
oc-llamacpp |
| Remote GPU server | Any reachable OpenAI-compatible URL | Add it to opencode.json |
The helper commands synchronize that server and launch OpenCode:
oc-ollama
oc-vllm
oc-lmstudio "Review this repository"They are prefixed with oc-, so they never replace the real ollama, vllm, or server commands on your computer.
Load or remove a model on the server and OpenCode sees the change on the next sync.
The synchronizer updates provider models without replacing unrelated settings, agents, MCP servers, permissions, themes, or keybindings.
API keys remain in environment variables or OpenCode's own credential store. Generated provider entries use safe references such as:
"apiKey": "{env:REMOTE_API_KEY}"A model can run on your laptop, desktop, home server, LAN workstation, or trusted Tailscale machine. If the endpoint is reachable and OpenAI-compatible, it can be synchronized.
A sleeping GPU box or closed LM Studio window should not stop OpenCode from opening. Launch checks use short timeouts and skip unavailable endpoints.
flowchart LR
A[Your model server] -->|lists available models| B[OpenCode Local Setup]
B -->|updates only provider models| C[Your opencode.json]
C --> D[OpenCode]
E[Environment variables] -->|safe secret references| C
In plain English:
- It reads the OpenCode configuration you already use.
- It accepts normal JSON or JSONC with comments and trailing commas.
- It asks each configured server for its live model list.
- It refreshes model names and supported metadata.
- It removes models that are no longer served, unless configured otherwise.
- It writes the file safely and keeps it private to your user account.
opencode # Open OpenCode with a quick pre-launch sync
sync-models # Refresh your configured compatible servers
opencode models # Show available provider/model IDs
opencode models --refresh # Refresh OpenCode's built-in provider cache
opencode auth login # Connect a built-in cloud provider
oc-doctor # Check config health and secret hygiene
opencode upgrade # Upgrade OpenCodeEdit the small environment file created by the installer:
$EDITOR ~/.config/opencode/local-setup/.env.localFor example:
LOCAL_API_BASE=http://127.0.0.1:11434/v1
OPENCODE_PROVIDER_ID=ollama
OPENCODE_PROVIDER_NAME="Ollama"Then run:
sync-modelsAdd a provider to ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"gpu-box": {
"npm": "@ai-sdk/openai-compatible",
"name": "My GPU Box",
"options": {
"baseURL": "http://100.100.100.100:8000/v1",
"apiKey": "{env:REMOTE_API_KEY}"
},
"models": {}
}
}
}Export the key only when the server requires one:
export REMOTE_API_KEY="your-key"
sync-modelsTailscale discovery is available for trusted networks, but remains off by default. Explicit providers work without any scanning.
Enable narrowly scoped Tailscale discovery
export OPENCODE_TAILSCALE_DISCOVERY=1
export OPENCODE_TAILSCALE_PORTS=1234,8000,8080,11434
sync-modelsOnly online peers and the ports you list are checked.
- Raw API keys are not written into generated configuration.
- Existing OpenCode settings are preserved.
- Config updates are atomic, reducing the chance of a half-written file.
- File permissions are restricted to your user.
- Tailscale discovery is opt-in.
- Post-exit synchronization is opt-in.
- Automatic session sharing is not enabled.
Run the built-in health check whenever something feels wrong:
oc-doctorcd opencode-local-setup
git pull
./scripts/install.sh
oc-doctorYour existing opencode.json and local environment file are preserved.
- Run private or local models while coding.
- Swap models frequently in LM Studio or Ollama.
- Serve models with vLLM or llama.cpp.
- Use a separate GPU workstation or home server.
- Want a clean OpenCode setup without maintaining model IDs by hand.
npm run validateThe validation suite covers JSONC parsing, model metadata migration, secure credential handling, atomic writes, multi-provider refresh, installation behavior, and opt-in Tailscale discovery.