How to Enable the Local Model Toggle in ImageStudio: Complete Developer Guide

The local model toggle automatically appears in ImageStudio when the Electron build detects a functional local inference client via isLocalAIAvailable(), allowing you to switch between ☁ API and ⚡ Local generation modes.

In the Anil-matcha/Open-Generative-AI repository, ImageStudio provides a seamless interface for both cloud-based and local AI image generation. Enabling the local model toggle requires specific runtime conditions and proper binary configuration, which this guide explains using the actual source implementation from src/components/ImageStudio.js.

Prerequisites for the Local Model Toggle

The toggle button does not appear in standard browser builds. You must satisfy three conditions derived from the conditional rendering logic in the source code:

1. Run the Electron desktop build. The local inference client only loads within the Electron runtime environment, not in web browsers.
2. Install local inference binaries. The application must locate functional local AI binaries on the system path.
3. Verify isLocalAIAvailable() returns true. This function in lib/localInferenceClient.js validates that the local backend can initialize properly.

When these conditions are met, the UI automatically injects the toggle button into the control toolbar without requiring manual configuration changes.

How the Toggle Is Implemented in ImageStudio

Inside src/components/ImageStudio.js, the application conditionally creates the toggle DOM element only after verifying local AI availability. The implementation follows this pattern:

// src/components/ImageStudio.js
import { isLocalAIAvailable } from '../lib/localInferenceClient.js';
import { LOCAL_MODEL_CATALOG, getLocalModelById } from '../lib/localModels.js';

let useLocalModel = false;
let selectedLocalModel = LOCAL_MODEL_CATALOG[0]?.id || null;

if (isLocalAIAvailable()) {
    const localToggleBtn = document.createElement('button');
    localToggleBtn.id = 'local-toggle-btn';
    localToggleBtn.className = 'flex items-center gap-1.5 px-3 py-2 rounded-xl transition-all border text-xs font-bold whitespace-nowrap';
    
    // Initial style setup
    updateLocalToggleStyle();
    controlsLeft.appendChild(localToggleBtn);
}

The button receives ID local-toggle-btn and appends to controlsLeft, appearing alongside the model and aspect-ratio selectors. If isLocalAIAvailable() returns false, this code block executes entirely, leaving no toggle in the interface.

Understanding the Toggle State and UI Updates

The toggle operates through a state variable useLocalModel that switches the generation mode and updates visual elements. The updateLocalToggleStyle() function manages the appearance differences:

• API Mode ("☁ API"): Uses bg-white/5 border-white/5 text-white/60 classes with hover effects
• Local Mode ("⚡ Local"): Uses bg-primary/20 border-primary/40 text-primary classes for emphasis

When clicked, the handler toggles the state and updates the model label to reflect the active source:

localToggleBtn.onclick = (e) => {
    e.stopPropagation();
    useLocalModel = !useLocalModel;
    updateLocalToggleStyle();

    if (useLocalModel) {
        const lm = getLocalModelById(selectedLocalModel);
        if (lm) document.getElementById('model-btn-label').textContent = lm.name;
    } else {
        document.getElementById('model-btn-label').textContent = selectedModelName;
    }
};

While useLocalModel equals true, the model dropdown renders entries from LOCAL_MODEL_CATALOG defined in lib/localModels.js rather than fetching remote API models. Selecting a local model updates selectedLocalModel and refreshes the aspect-ratio selector accordingly.

Troubleshooting: When the Toggle Does Not Appear

If the "☁ API"/"⚡ Local" button is missing from your toolbar, verify these specific failure points:

• Wrong runtime environment. Browser builds cannot access local system binaries. Ensure you launched the application via Electron.
• Missing inference binaries. The isLocalAIAvailable() function returns false when binaries are absent or incompatible with your platform. Check that local AI executables are installed and accessible.
• Import path errors. Verify that lib/localInferenceClient.js and lib/localModels.js exist in your build and export the expected functions and catalogs.

Summary

• Electron requirement: The local model toggle only renders in the desktop Electron build, not browser versions.
• Automatic detection: The UI checks isLocalAIAvailable() from lib/localInferenceClient.js before creating the toggle element.
• State management: The useLocalModel boolean tracks mode status, while selectedLocalModel stores the chosen local model ID from LOCAL_MODEL_CATALOG.
• Visual feedback: The toggle switches between "☁ API" (cloud) and "⚡ Local" (lightning) labels with distinct CSS classes for each state.
• Model sourcing: Local mode populates the model dropdown using LOCAL_MODEL_CATALOG instead of remote API entries.

Frequently Asked Questions

Why is the local model toggle not showing in ImageStudio?

The toggle fails to appear when isLocalAIAvailable() returns false, which occurs if you are running the browser version instead of the Electron build, or when local inference binaries are missing from your system. Ensure you are running the desktop application and that the local AI backend binaries are properly installed and accessible to the process.

What determines which models appear in the dropdown when the toggle is active?

When you switch to "⚡ Local" mode by setting useLocalModel = true, the application queries LOCAL_MODEL_CATALOG from lib/localModels.js to populate the model selector. This catalog contains metadata for bundled local models, replacing the remote API model list that appears in "☁ API" mode. The selectedLocalModel variable tracks your chosen entry from this catalog.

How does the toggle affect image generation requests?

The useLocalModel state variable acts as a switch between inference backends. When false, ImageStudio routes generation requests to the remote cloud API. When true, the application uses the localAI interface exported from lib/localInferenceClient.js to process images using your local hardware and selected model from LOCAL_MODEL_CATALOG.

Can I programmatically force local mode without the toggle button?

While you can manually set useLocalModel = true in the code, generation will fail unless isLocalAIAvailable() returns true and valid local binaries exist. The toggle button is the intended user interface for this switch, located in src/components/ImageStudio.js, and its presence confirms that the local inference client is properly initialized and ready for use.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}