opencode-lmstudio-sync

opencode-lmstudio-sync is an OpenCode plugin that discovers the models exposed by a local LM Studio server and merges them into the OpenCode runtime configuration at startup.

It keeps user-authored model entries intact, fills in missing metadata when available, and avoids writing back to the user's config file by default.

Features

• Discovers authoritative model IDs from LM Studio GET /v1/models
• Optionally enriches model names and context limits from GET /api/v1/models
• Creates or completes the lmstudio provider at runtime when needed
• Preserves user-defined model names and context limits by default
• Supports optional prune and refresh flags for plugin-generated entries
• Uses short in-memory caching to avoid repeated network calls
• Works on Windows, macOS, and Linux

Platform Support

The plugin logic is cross-platform.

• Windows: supported. The probe order checks 127.0.0.1:15432 and localhost:15432 first, which matches common LM Studio setups on Windows.
• macOS: supported. If OpenCode loads the plugin from a protected folder such as Documents, the app may need explicit file access in macOS privacy settings.
• Linux: supported. If OpenCode is installed through Flatpak or Snap, filesystem sandboxing may require additional access to the plugin directory.

Installation

Option 1: Install through OpenCode as an npm plugin

Use this after publishing the package to npm.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-lmstudio-sync@latest"]
}

Optional explicit LM Studio base URL:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-lmstudio-sync@latest"],
  "provider": {
    "lmstudio": {
      "options": {
        "baseURL": "http://127.0.0.1:15432/v1"
      }
    }
  }
}

Full explicit provider:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-lmstudio-sync@latest"],
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:15432/v1"
      }
    }
  }
}

Option 2: Run it from a local checkout

1. Clone the repository.
2. Install dependencies.
3. Build the project.
4. Add a small local loader file in your OpenCode plugin directory.

Build commands:

npm install
npm run build

Local loader example:

CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
OPENCODE_DIR="$CONFIG_HOME/opencode"
PLUGIN_DIR="/absolute/path/to/opencode-lmstudio-sync"

mkdir -p "$OPENCODE_DIR/plugins"

cat > "$OPENCODE_DIR/plugins/opencode-lmstudio-sync.js" <<EOF2
export { LMStudioPlugin } from "$PLUGIN_DIR/dist/index.js";
EOF2

If your OpenCode installation uses a different config root, place the loader file inside that installation's plugin directory instead.

Base URL Resolution

The plugin resolves the LM Studio base URL in this order:

1. provider.lmstudio.options.baseURL
2. LM_STUDIO_BASE_URL
3. Probing these bases in order:
   • http://127.0.0.1:15432
   • http://localhost:15432
   • http://127.0.0.1:1234
   • http://localhost:1234
   • http://127.0.0.1:8080
   • http://localhost:8080
   • http://127.0.0.1:11434
   • http://localhost:11434

Accepted values are normalized to <base>/v1.

Environment Variables

• LM_STUDIO_BASE_URL: use an explicit LM Studio server URL
• LM_STUDIO_API_TOKEN: optional bearer token for /api/v1/models
• LMSTUDIO_PRUNE_MISSING=1: remove plugin-generated models that are no longer returned by /v1/models
• LMSTUDIO_REFRESH_EXISTING=1: refresh metadata for existing plugin-generated entries

Behavior Notes

• GET /v1/models is the source of truth for which models appear in OpenCode.
• GET /api/v1/models is optional enrichment only.
• User-defined name values are preserved.
• User-defined limit.context values are preserved unless refresh is explicitly enabled for plugin-generated entries.
• The plugin tracks generated models in memory instead of adding custom marker fields to the config.
• The plugin mutates the runtime config object and does not write to the user's config file.

Example Runtime Merge

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-lmstudio-sync@latest"],
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": {
        "baseURL": "http://127.0.0.1:15432/v1"
      },
      "models": {
        "google/gemma-3n-e4b": {
          "name": "Gemma 3n-e4b",
          "organizationOwner": "google",
          "limit": {
            "context": 8192
          }
        }
      }
    }
  }
}

Development

npm install
npm run build
npm run typecheck
npm test

Troubleshooting

• LM Studio is not detected: make sure the local server is running and exposing the OpenAI-compatible API.
• Models do not appear: verify that GET /v1/models returns the expected IDs.
• Metadata is missing: the plugin still works without /api/v1/models, but display names and context limits may be less detailed.
• macOS cannot load the plugin from Documents: give OpenCode access to that folder or move the project to a less restricted path.
• Linux sandboxed app cannot read the plugin directory: grant filesystem access or move the project to a path visible to the app.

License

MIT