OpenCode Dynamic Model Virtualizer (FUSE Driver)

An intelligent, zero-disk-footprint virtual file system layer built with FUSE and Python (uv).

This driver intercepts system read calls to opencode.json inside your .config/opencode/ workspace. It reads your physical base configurations from a file named static-opencode.json, scans for custom providers lacking hardcoded models, dynamically queries their OpenAI-compatible /v1/models endpoints over the network, maps their capabilities, and feeds the dynamically merged JSON object directly back into OpenCode in real time.

---

Architecture Blueprint

Standard virtual file system drivers require root privileges or kernel-level compilation. This implementation acts purely in the user space via FUSE loop-mount bindings:

+------------------+       System Read       +----------------------+
|   OpenCode CLI   | ──────────────────────> | ~/.config/opencode/  |
+------------------+                         |    opencode.json     |
         ▲                                   +----------┬-----------+
         │                                              │
         │ Streamed Data (In-Memory Only)               │ (Follows Symlink)
         │                                              ▼
+--------┴---------+       Triggers Read     +----------------------+
|  Python FUSE FS  | <────────────────────── |       fuse-dir/      |
+--------┬---------+                         +----------------------+
         │
         ├─► [1] Reads Local File ────► ~/.config/opencode/static-opencode.json
         │
         └─► [2] Queries Over Network ──► http://<custom-provider>/v1/models

---

Core Features

• Zero Hardcoding Required: Simply define your custom OpenAI/OmniRoute endpoint inside your base profile, and let the driver map available endpoints dynamically on every CLI launch.
• Smart Failure & Parameter Estimation: Automatically falls back to standard industry presets (e.g., $128\text{k}$ token context windows, $4\text{k}$ outputs) if downstream custom APIs leave out standard telemetry metrics.
• Clean Namespace Isolation: Maps the model name parameter to mirror its global id exactly. This ensures that duplicate version structures (e.g., provider-a/gpt-5.5 and provider-b/gpt-5.5) remain distinguishable in your OpenCode model picker interface.
• No Sudoless Dependencies: Built natively to execute in standard unprivileged space via fusepy.

---

Installation & Deployment Checklist

1. Prerequisites

Ensure you have the native fuse3 libraries installed via your Linux package distribution manager, alongside Astral’s Python manager uv:

# Ubuntu/Debian core environments
sudo apt install fuse3

# Install uv if you don't already have it
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Configure Your Source File Blueprint

Create a physical file called static-opencode.json inside your target profile path (~/.config/opencode/).

Omit the "models": {} object completely from any custom providers you wish to have dynamically discovered:

{
    "$schema": "https://opencode.ai/config.json",
    "theme": "rosepine",
    "provider": {
        "my-omniroute-server": {
            "npm": "@ai-sdk/openai-compatible",
            "name": "OmniRoute Infrastructure Server",
            "options": {
                "baseURL": "http://127.0.0.1:8000/v1",
                "apiKey": "sk-dummy-token-key"
            }
        }
    }
}

3. Spin Up the Virtual FUSE Machine

Run the script using uv run. uv automatically looks at the inline PEP 723 script metadata block, creates an isolated virtual environment shell, resolves all networking/mount packages, and sets up your dynamic virtual file under fuse-dir/opencode.json:

uv run virtual_config.py ~/.config/opencode/static-opencode.json

(Keep this terminal tab running in the background).

4. Create the Workspace Symbol Link

Open a separate shell terminal tab, clear out any static old config files if they exist, and map a secure symbolic link to connect OpenCode directly to your new FUSE machine:

# Clear any existing static hard file block
rm -f ~/.config/opencode/opencode.json

# Create symlink pointing directly to the live FUSE mount channel
ln -s $(pwd)/fuse-dir/opencode.json ~/.config/opencode/opencode.json

---

Verification & Tear Down Testing

Testing

You can inspect the system pipeline directly using standard terminal tooling. Executing a standard system cat call triggers the underlying hook to update your JSON live:

cat ~/.config/opencode/opencode.json

Graceful Termination

To safely tear down the virtual network interface loop and clear out active processing threads, send a shutdown command via your package system:

fusermount3 -u fuse-dir