diff --git a/docs/README.md b/docs/README.md index 695271779..29cbcbac2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -52,11 +52,7 @@ Current Status: In-progress - Structure is in-place and planned docs are current - Community Workflows *(planned)* — Browsing community workflows via OpenArt ### Settings -- Overview *(planned)* — Navigating the settings hub -- General *(planned)* — Theme, language, data directory, and shared folder settings -- Accounts *(planned)* — Lykos account, OAuth login, and API tokens -- Inference Settings *(planned)* — Inference UI behavior and defaults -- Updates *(planned)* — Auto-update channel and frequency settings +- [Settings](settings/settings.md) — All application settings covering General, Accounts, Checkpoint Manager, Package Environment, Model Browser, Workflow Browser, Console, Appearance, System, and Debug Options ### Advanced - [Overview](advanced/overview.md) — Advanced configuration and technical reference diff --git a/docs/advanced/environment-variables.md b/docs/advanced/environment-variables.md index bcd534d02..0e1ef004b 100644 --- a/docs/advanced/environment-variables.md +++ b/docs/advanced/environment-variables.md @@ -143,26 +143,31 @@ Most users should leave these alone unless they are troubleshooting a specific R | `COMFYUI_ENABLE_MIOPEN` | `1` | Tells ComfyUI to keep the MIOpen-backed path enabled on ROCm builds where it may otherwise be disabled by default. Without this enabled, ComfyUI disables the `cudnn` backend path in its backend calls for RDNA3, RDNA3.5, and RDNA4 AMD GPUs, which in turn disables the MIOpen-backed functions that rely on that path. This variable is needed for MIOpen to function properly in those setups. | | `TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL` | `1` | Enables the experimental ROCm AOTriton path in compatible PyTorch builds. In Stability Matrix's Windows ROCm ComfyUI integration, this is used for TheRock technical-preview PyTorch builds to enable AOTriton-provided built-in Flash Attention and PyTorch SDPA memory-efficient attention paths. | -For some Windows ROCm-based ComfyUI launches, Stability Matrix already applies several of these optimizations automatically in package code, including: +For Windows ROCm-based WebUI package launches, Stability Matrix already applies several of these optimizations automatically at package launch as a general all-round baseline. Variables automatically utilized at package launch include: -`MIOPEN_FIND_MODE=2` - -`MIOPEN_SEARCH_CUTOFF=1` - -`MIOPEN_FIND_ENFORCE=1` - -`TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1` (RDNA3 / RDNA3.5 / RDNA4 only, and additionally excluded on the gfx1152/gfx1153 APU architectures where AOTriton isn't yet supported) - -`FLASH_ATTENTION_TRITON_AMD_ENABLE=TRUE` - -`COMFYUI_ENABLE_MIOPEN=1` (RDNA3 / RDNA3.5 / RDNA4 only, no gfx1152/gfx1153 exclusion) - -`PYTORCH_ALLOC_CONF=max_split_size_mb:512,garbage_collection_threshold:0.8` +| Variable | Value | Notes | +|---|---|---| +| `MIOPEN_FIND_MODE` | `2` | | +| `MIOPEN_SEARCH_CUTOFF` | `1` | | +| `MIOPEN_FIND_ENFORCE` | `1` | | +| `TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL` | `1` | Enables the experimental ROCm AOTriton path. Applied only on RDNA3 / RDNA3.5 / RDNA4 GPUs, and additionally excluded on gfx1152/gfx1153 APU architectures where AOTriton isn't yet supported. | +| `FLASH_ATTENTION_TRITON_AMD_ENABLE` | `TRUE` | Enables the Triton-based Flash Attention implementation for AMD GPUs, providing an efficient attention path when the native ROCm Flash Attention is unavailable and instead provided by a separate FA Python package. | +| `COMFYUI_ENABLE_MIOPEN` | `1` | Keeps the MIOpen-backed path enabled in ComfyUI on RDNA3 / RDNA3.5 / RDNA4 GPUs. | +| `PYTORCH_ALLOC_CONF` | `max_split_size_mb:512,garbage_collection_threshold:0.8` | | + +Environment Variables automatically enabled for legacy AMD GPU architectures (Vega/GCN5, RDNA1, RDNA2) where certain backend paths are not supported by the hardware or supported well: +| Variable | Value | Notes | +|---|---|---| +| `TORCH_BACKENDS_CUDA_FLASH_SDP_ENABLED` | `0` | Disables the Flash SDP backend. | +| `TORCH_BACKENDS_CUDA_MEM_EFF_SDP_ENABLED` | `0` | Disables the memory-efficient SDP backend. | +| `TORCH_BACKENDS_CUDA_MATH_SDP_ENABLED` | `1` | Enables the math SDP backend as the fallback attention implementation. | -Linux installs do not currently get the same automatic overrides, so they will need to be enabled by the user. +> [!NOTE] +> Linux installs do not currently get the same automatic overrides, so they will need to be enabled by the user. -If you're using the ComfyUI-Zluda package specifically, it also sets its own environment variables at launch on top of the above: `FLASH_ATTENTION_TRITON_AMD_ENABLE=TRUE`, `MIOPEN_FIND_MODE=2`, `MIOPEN_LOG_LEVEL=3`, and `ZLUDA_COMGR_LOG_LEVEL=1`. If you're wondering why those already appear to be set for a ZLUDA install, this is why. +> [!NOTE] +> ComfyUI-Zluda is not managed by Stability Matrix's internal ROCm handling. If you're using the ComfyUI-Zluda package specifically, it also sets its own environment variables at launch similar to some of the above: `FLASH_ATTENTION_TRITON_AMD_ENABLE=TRUE`, `MIOPEN_FIND_MODE=2`, `MIOPEN_LOG_LEVEL=3`, and `ZLUDA_COMGR_LOG_LEVEL=1`. If you're wondering why those already appear to be set for a ZLUDA install, this is why. Whatever you set in Stability Matrix's own environment-variable editor is applied last, so it always overrides these auto-applied defaults if the same variable name is used. diff --git a/docs/advanced/hardware-support.md b/docs/advanced/hardware-support.md index de17a74ce..ad74692cb 100644 --- a/docs/advanced/hardware-support.md +++ b/docs/advanced/hardware-support.md @@ -40,11 +40,11 @@ The lists below describe what the code checks for. Because hardware detection wo ## AMD on Windows -AMD support on Windows is the most involved case, because there are three different paths depending on your GPU and package: native ROCm (technical preview), ZLUDA, and DirectML. +AMD support on Windows is the most involved case, because there are three different paths depending on your GPU and package: native ROCm, ZLUDA, and DirectML. -### Native ROCm (TheRock technical preview) +### Native ROCm -Stability Matrix can install AMD's native ROCm PyTorch on Windows using AMD's TheRock multi-architecture wheels. This path is gated to a specific set of GPU architectures. The code recognizes the following `gfx` architectures as supported on Windows: +Stability Matrix can install AMD's native ROCm PyTorch on Windows using AMD's official multi-architecture wheels. This path is gated to a specific set of GPU architectures. The code recognizes the following `gfx` architectures as supported on Windows: - **RDNA4** — `gfx120x` (e.g. RX 9070, RX 9060 families). - **RDNA3 / RDNA3.5** — `gfx110x` (RDNA3 desktop and mobile) and `gfx115x` (RDNA3.5 APUs such as the 890M / 8060S / Z2 Extreme families). @@ -54,15 +54,17 @@ Architectures in the `gfx110x`, `gfx115x`, and `gfx120x` ranges are treated as " **What Stability Matrix does automatically:** -- When a supported AMD GPU is present on Windows, ROCm becomes the recommended backend for ROCm-capable packages (currently ComfyUI and Comfy-based flows via SwarmUI). -- Torch is installed from AMD's ROCm multi-arch index (`repo.amd.com/rocm/whl-multi-arch/`) as device-specific wheels (`torch[device-gfxNNNN]`). Vega parts (`gfx900` / `gfx906`) pull from the nightly multi-arch feed instead, since TheRock currently only publishes their device packages there. +- When a supported AMD GPU is present on Windows, ROCm becomes the recommended backend for ROCm-capable packages. +- Torch is installed from AMD's ROCm multi-arch index (`repo.amd.com/rocm/whl-multi-arch/`) as device-specific wheels (`torch[device-gfxNNNN]`). Vega parts (`gfx900` / `gfx906`) pull from the 'TheRock' nightly multi-arch feed instead, since these architecture builds currently are only available there instead of the stable production distribution stream. - On modern architectures it applies a set of ROCm performance and attention environment variables at launch (MIOpen find-mode tuning, AOTriton experimental flash attention, `COMFYUI_ENABLE_MIOPEN`, and an allocator tuning string). AOTriton is excluded on the `gfx1152` / `gfx1153` APU architectures, which it does not yet support. Legacy architectures instead force a math SDP fallback. The full variable list and exactly which ones are auto-applied are documented in [Environment Variables](environment-variables.md#amd-and-rocm-variables). -- ComfyUI offers optional extra commands for supported AMD GPUs, including **Install Triton and SageAttention (ROCm)**, **Install Flash Attention (ROCm)** (legacy architectures), an **Install ROCm Development SDK** step, and an **Install bitsandbytes (ROCm)** step for Python 3.12 environments. +- ComfyUI offers optional extra commands for supported AMD GPUs, including **Install Triton and SageAttention (ROCm)** (Sage Attention 1.x), **Install Flash Attention (ROCm)** (legacy architectures), an **Install ROCm Development SDK** step, and an **Install bitsandbytes (ROCm)** step for Python 3.12 environments. +- **Packages:** ComfyUI, Stable Diffusion WebUI Reforge, InvokeAI, SwarmUI, and Wan2GP are supported by this install path. + > [!NOTE] While not managed by Stability Matrix for ROCm installs, SD.Next has a Windows-native ROCm install when the "ROCm" Pytorch index is selected in Advanced Installation Options during initial package install and `--use-rocm` is set in launch options. This install path is internally handled by SD.Next itself and currently only supports RDNA2 dedicated GPUs, RDNA3, RDNA3.5, and RDNA4 GPUs. **Caveats:** -- Windows AMD ROCm is explicitly experimental. Stability Matrix prints a notice asking you to report issues to Stability Matrix first, since the setup may not be officially supported by the upstream package developers. -- Only the architectures listed above are eligible. If your AMD GPU is not on the list, the recommended default becomes ZLUDA or DirectML instead. +- Windows AMD ROCm implementation for Stability Matrix is explicitly in an experimental state. While these package installations are generally in a working state, untested or edge-case issues and incompatibilities may appear. Stability Matrix prints a notice asking you to report issues to Stability Matrix first, since the setup may not be officially supported by the upstream package developers. +- Only the architectures listed above are eligible. If your AMD GPU is not on the list, the recommended default becomes ZLUDA or DirectML instead. For a more detailed list of compatible AMD GPU architectures, please refer to the ROCm/TheRock [GPU Support](https://github.com/ROCm/TheRock/blob/main/SUPPORTED_GPUS.md#rocm-on-windows) table. ### ZLUDA diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md index 6b45dff2b..96209b748 100644 --- a/docs/getting-started/overview.md +++ b/docs/getting-started/overview.md @@ -43,7 +43,7 @@ Stability Matrix is cross-platform, but the exact release formats and hardware t | Operating System | Version / Target | Architecture | Notes | |---|---|---|---| | Windows | Windows 10 and Windows 11 | x64 | Official release builds are published for `win-x64`. This is the broadest-supported desktop target for Stability Matrix and most package workflows. | -| Linux | Modern x86-64 desktop distributions | x64 | Official Linux releases are published for `linux-x64`, primarily as an AppImage, with an AUR package also available for Arch-based systems. Depending on the distribution, AppImage/runtime support packages such as `libfuse2`, `libappimage`, or `libxcrypt-compat` may be needed if they are not already provided by the system. | +| Linux | Modern x86-64 desktop distributions | x64 | Official Linux releases are published for `linux-x64`, primarily as an AppImage, with an AUR package also available for Arch-based systems. Depending on the distribution, runtime support packages such as `fuse3` or `libxcrypt-compat` may be needed if they are not already provided by the system. | | macOS | Apple Silicon Macs, with macOS 12.3 or later recommended for AI workflows | arm64 | Official macOS releases are published for Apple Silicon (`osx-arm64`) as a `.dmg`. The app's AI workflows rely on the MPS backend on Apple Silicon. | In other words, the practical supported release targets are Windows x64, Linux x64, and Apple Silicon macOS. Some project files include additional runtime identifiers, but the documented source-build support and the release pipeline currently focus on `win-x64`, `linux-x64`, and `osx-arm64`. For work from a local checkout instead of a packaged release, a planned Building from Source and Contributing page will serve as the documentation entry point and link to the repository's contributor guide. diff --git a/docs/package-manager/installing-packages.md b/docs/package-manager/installing-packages.md index be594f12b..a060a36e6 100644 --- a/docs/package-manager/installing-packages.md +++ b/docs/package-manager/installing-packages.md @@ -96,7 +96,7 @@ The **PyTorch backend** determines which GPU acceleration library your package u | Backend | Platform | GPU | Notes | |---------|----------|-----|-------| | **CUDA** | Windows, Linux | NVIDIA (GTX 900-series and newer) | Best performance and broadest compatibility. CUDA toolkit is bundled with PyTorch; no separate driver installation beyond standard NVIDIA drivers. Turing (RTX 2000-series) or newer recommended. | -| **ROCm** | Windows, Linux | AMD (select GPUs per platform) | Native AMD GPU acceleration. On Linux, requires system-level ROCm installation. On Windows, uses AMD's TheRock technical preview builds. Per-chip compatibility details are planned for a future Hardware Support page. | +| **ROCm** | Windows, Linux | AMD (select GPUs per platform) | Native AMD GPU acceleration. On Linux, requires system-level ROCm installation. Package support is more limited on Windows. Per-chip compatibility details are planned for a future Hardware Support page. | | **DirectML** | Windows | AMD, Intel, some NVIDIA | Microsoft's DirectML API. Broad compatibility but slower performance than CUDA or ROCm. Development is largely stagnant; consider native ROCm, or ZLUDA if need be, as an alternative for AMD GPUs. | | **ZLUDA** | Windows | AMD (via CUDA translation layer) | Experimental CUDA-to-AMD translation layer. Used by the ComfyUI-Zluda, SD.Next, and AMDGPU Forge packages. Generally faster than DirectML for supported operations. | | **IPEX** | Windows, Linux | Intel Arc (discrete and integrated) | Intel Extension for PyTorch. Requires Intel Arc GPU (A-series, B-series) or modern Intel Core Ultra with integrated Arc graphics. | diff --git a/docs/settings/settings.md b/docs/settings/settings.md new file mode 100644 index 000000000..69069b0e6 --- /dev/null +++ b/docs/settings/settings.md @@ -0,0 +1,342 @@ +# Settings + +The Settings page is the central configuration hub for Stability Matrix. It is organized into categories that cover general application behavior, integrations, package management, browsing, appearance, and system-level configuration. These settings can be accessed via the Settings link in the bottom-left of the Stability Matrix UI. + +[`Home`](../README.md) + +## Table of Contents + +- [General](#general) +- [Integrations](#integrations) +- [Checkpoint Manager](#checkpoint-manager) +- [Package Environment](#package-environment) +- [Model Browser](#model-browser) +- [Workflow Browser](#workflow-browser) +- [Console](#console) +- [Appearance](#appearance) +- [System](#system) +- [About](#about) +- [Debug Options](#debug-options) + +--- + +## General + +Controls Inference UI behavior, prompt auto-completion, and notification preferences. + +### Inference + +Inference settings control the behavior of Stability Matrix's built-in image generation and prompt editing tools. They are organized into three groups: **Prompt**, **General**, and **Dimensions**. + +#### Prompt + +**Auto Completion** provides tag suggestions as you type in prompt and negative prompt text boxes. When enabled, a dropdown appears with matching tags from a configurable CSV file. + +| Setting | Description | +|---|---| +| **Enable Auto Completion** | Toggle the tag suggestion feature on or off. | +| **Prompt Tags** | Select which CSV tag file to use for completions. Custom tag CSVs can be imported via the **Import** button. Imported CSVs are copied to the `Tags/` folder inside the data directory. | +| **Replace underscores with spaces** | When enabled, underscores in completed tags are displayed as spaces (e.g., `oil_painting` shows as `oil painting`). | + +#### General + +| Setting | Description | +|---|---| +| **Filter Extra Networks by Base Model** | When enabled, LoRA and extra network model lists are filtered to only show models compatible with the currently selected base model (e.g., SDXL LoRAs when SDXL is selected). | +| **Image Viewer — Show pixel grid at high zoom** | When enabled, a pixel grid overlay appears when zooming into generated images. | +| **Image Viewer — Move files to Recycle Bin** | When enabled, deleted images go to the system Recycle Bin / Trash instead of being permanently erased. Only shown on platforms where Recycle Bin is available. | +| **Output Image Files — File name pattern** | A format string for naming saved output images, using variables like `{model_name}` and `{seed}`. Clicking the text field shows all available variables. Default: `{model_name}_{seed}_{width}x{height}`. | +| **Floating Search** | When enabled, all combo boxes use floating search mode where typed text appears as an overlay and auto-selects the first match. | + +#### Dimensions + +| Setting | Description | +|---|---| +| **Step Size** | How much width/height values change per step when using arrow buttons or scroll wheel on dimension inputs. Range: 8–1024 pixels. | +| **Favorite Dimensions** | A configurable list of frequently used width × height pairs that appear as quick-select options in the Inference UI. Add via the **+ Add** button, remove by selecting a row and clicking **Remove**. Saved automatically. | + +### Notifications + +Controls how Stability Matrix alerts you about events. Each notification type can be independently set to one of three channels: + +| Channel | Description | +|---|---| +| **None** | No notification is sent. | +| **In-App** | A toast notification appears inside the Stability Matrix window. | +| **Desktop** | A native OS push notification (Windows Action Center, macOS Notification Center). | + +> [!NOTE] +> On Linux, the default channel is **In-App** for all events since native push support varies across desktop environments. + +| Event | Default | +|---|---| +| Inference Prompt Completed | Desktop (In-App on Linux) | +| Inference Batch Completed | Desktop (In-App on Linux) | +| Download Completed | Desktop (In-App on Linux) | +| Download Failed | Desktop (In-App on Linux) | +| Download Canceled | Desktop (In-App on Linux) | +| Package Install Completed | Desktop (In-App on Linux) | +| Package Install Failed | Desktop (In-App on Linux) | + +--- + +## Integrations + +The Integrations section connects Stability Matrix to external services and platforms. + +### Accounts + +The Accounts sub-page manages external service credentials. Connecting accounts allows Stability Matrix to download models that require authentication, access membership features, and use cloud-based image generation services. + +#### Membership and Lykos Account + +A Lykos account is the central identity for Stability Matrix. Signing in unlocks membership benefits and account-linked features. Membership is managed at [lykos.ai/membership](https://lykos.ai/membership). + +| Tier | Description | +|---|---| +| **Visionary** | Highest monthly credits and vote power. Shout-out in both release and Preview/Dev changelog. Maximum support for development. | +| **Pioneer** | Higher monthly credits and vote power. Shout-out in release changelog. | +| **Insider** | Increased credits and vote power over Supporter. Accelerated Model Discovery | +| **Supporter** | 1,000 monthly credits, 2× vote power. The entry-level tier that supports development and server costs. | + +All support tiers receive early access to new features through **Preview** and **Dev** update channels. + +When you are an active subscriber, the Accounts page shows your tier, the date you started supporting, and a quick link to manage your membership. A thank-you message and community Discord link are also displayed. + +If you are not subscribed, a membership card appears with a **Become a Supporter** button that opens the Lykos membership page in your browser. + +**Connecting**: Click **Connect** under the Lykos section. A device authentication dialog appears with a code. Open the URL in your browser, enter the code, and authorize. Authentication happens entirely in your browser — no credentials are entered into Stability Matrix. + +Your profile image is fetched from [Gravatar](https://gravatar.com/) using your Lykos account email. Click the image to manage your Lykos account, edit your Gravatar, or copy your user ID. + +#### CivitAI API Key + +Enables downloading early-access models from CivitAI and browsing NSFW-tagged models (requires enabling the NSFW toggle in the Model Browser). + +**To connect**: Log in to [civitai.com](https://civitai.com), go to **Account Settings → API Keys**, create a key, and paste it into the Connect dialog in Stability Matrix. The key is validated by fetching your CivitAI profile. + +The API key is sent as a `Bearer` token in the `Authorization` header for all requests to `civitai.com`, including model downloads. + +#### HuggingFace Token + +Enables downloading gated models (e.g., FLUX) from the Hugging Face Hub. You must also accept the model's license terms on the Hugging Face website before downloading. + +**To connect**: Log in to [huggingface.co](https://huggingface.co), go to **Settings → Access Tokens**, create a **Read** token (starts with `hf_`), and paste it into the Connect dialog. Stability Matrix validates the token by calling the HuggingFace API. + +The token is used in two ways: sent as a `Bearer` header for direct downloads from `huggingface.co`, and available for manual injection into package environments via `HF_TOKEN` in the Environment Variables editor. + +> [!IMPORTANT] +> Disconnecting the token here does **not** remove a manually-set `HF_TOKEN` from the Environment Variables editor. Remove it from both places if needed. + +#### Gemini API Key + +Enables the **Nano Banana** image generation provider in the **Image Lab**, which uses Google's Gemini models. Requires a paid-tier Google AI account with billing enabled. + +**To connect**: Go to [Google AI Studio](https://aistudio.google.com/api-keys), create an API key, and paste it into the Connect dialog under the **Image Generation APIs** section. The key is validated at generation time when the Image Lab makes its first request. + +> [!IMPORTANT] +> When API keys are generated on their respective service website, it is recommended to save your API keys somewhere safe (e.g., text file, password/note manager, etc.) as these services will typically only provide this key once. + +#### How Credentials Are Stored + +All API keys and tokens are stored encrypted at rest in the `user-secrets.data` file. Keys are never written to plaintext. The file is encrypted using a key derived from system-specific identifiers, meaning it can only be decrypted on the same machine that wrote it. + +The `user-secrets.data` location depends on your operating system: + +| Platform | Path | +|---|---| +| Windows | `%APPDATA%\StabilityMatrix\user-secrets.data` (`C:\Users\{username}\AppData\Roaming\StabilityMatrix`) | +| Linux | `~/.config/StabilityMatrix/user-secrets.data` | +| macOS | `~/Library/Application Support/StabilityMatrix/user-secrets.data` | + +This is the fixed application data directory — distinct from the user-configurable library / data directory where packages and models are stored. + +### Discord Rich Presence + +When enabled, your Discord status shows that you are using Stability Matrix. + +--- + +## Checkpoint Manager + +Controls how model files are handled when imported and how shared model folders are managed. + +| Setting | Description | +|---|---| +| **Import Behaviour** | Choose whether to **Copy** or **Move** files when dragging and dropping them into the Checkpoint Manager. Copy leaves the original in place; Move relocates it. | +| **Remove Symlinks on Shutdown** | When enabled, Stability Matrix removes shared model symlinks and junction points when the application closes. | +| **Reset Checkpoints Cache** | Clears the cached checkpoint index. Use this if models are not appearing correctly or if the index becomes out of date. | + +--- + +## Package Environment + +Manages environment variables, Python tooling, and Git configuration used when launching packages. + +### Environment Variables + +Opens the global environment variable editor. Variables set here are injected into every launched package's process environment. This is useful for configuring PyTorch behavior, setting cache locations, or adding API tokens without editing scripts. + +Variables are defined as name/value pairs. Click **Edit** to open the editor, then click **+** to add a new row. Changes apply to future package launches — restart any running packages for new variables to take effect. + +Common uses include `PYTORCH_ALLOC_CONF` for GPU memory tuning, `HF_TOKEN` for HuggingFace authentication in packages, `CUDA_VISIBLE_DEVICES` for GPU isolation, and `PATH` modifications. See the [Environment Variables guide](../advanced/environment-variables.md) for a full reference. + +> [!NOTE] +> User-set environment variables take priority over any defaults Stability Matrix applies automatically at package launch. + +### Embedded Python + +Stability Matrix bundles its own Python installation (Python 3.10) stored in the `Assets/Python310/` folder inside the data directory. This embedded Python is separate from the various standalone Python versions used by package virtual environments and is used exclusively for Stability Matrix's own internal operations. + +Internally, the embedded Python powers: + +- **Virtual environment bootstrapping** — When setting up a package for the first time, the embedded Python is used to install `pip` and `virtualenv` into itself via Python.NET. These tools are then invoked to create the package's own isolated virtual environment. This same bootstrap process runs during one-click installs, data directory migration, and standard package installs. +- **Python version inspection** — The **Check Version** button in Settings uses Python.NET to initialize the embedded Python runtime in-process and retrieve detailed version information. + +The embedded Python section in Settings displays the current version and provides actions to run an arbitrary Python command utilizing the embedded Python, clear the Pip cache, or clear the uv cache. + +### Git + +Runs Git commands against the bundled Git installation. On Windows, also provides an option to enable long path support in Git. + +### Show Unsupported Python Versions + +When enabled, Python versions outside the supported range for a package are still shown as installation options. Typically left disabled unless troubleshooting. + +--- + +## Model Browser + +Configures the behavior of the CivitAI model browser. + +| Setting | Description | +|---|---| +| **Auto Search on Load** | When enabled, the Model Browser automatically runs a search with your last-used sort, period, and model type filters when the page opens. Results are sorted by Highest Rated by default. When disabled, you must manually trigger a search. Previous search parameters are restored from your last session regardless of this setting. | +| **Base Model Filter** | Toggle which base model types (SD1.5, SDXL, Pony, Illustrious, Anima, etc.) are shown or hidden in the `Base Model` filter for the Model Browser. | + +--- + +## Workflow Browser + +| Setting | Description | +|---|---| +| **Infinite Scrolling** | When enabled, the Workflow Browser continuously loads more results as you scroll. When disabled, results are paginated. | + +--- + +## Console + +| Setting | Description | +|---|---| +| **History Size** | Maximum number of log entries retained in the Console view. Set to `-1` for unlimited or `0` to disable history. (Default: 9001) | + +--- + +## Appearance + +| Setting | Description | +|---|---| +| **Theme** | Switch between Light, Dark, and System themes. Changes take effect immediately. | +| **Language** | Select the UI language from available community-contributed translations. | +| **Number Format** | Choose how numbers are formatted. Options include default system format or forced period/comma decimal separators. A live preview is shown in the dropdown. | +| **Holiday Mode** | Toggles a festive santa hat overlay on Model Browser card images. **Automatic** shows hats during December, **Enabled** forces them year-round, **Disabled** never shows them. | +| **Always Show Scrollbars** | When enabled, scrollbars are always visible. When disabled, they appear only while scrolling. | + +--- + +## System + +System-level settings for updates, data management, hardware preferences, and diagnostic information. + +### Updates + +| Setting | Description | +|---|---| +| **Update Channel** | Choose between **Stable** (tested releases), **Preview** (newer features, minor issues possible), and **Dev** (latest development builds). Preview and Dev channels require an active Lykos membership. | +| **Auto-Update Frequency** | How often Stability Matrix checks for updates: on startup, daily, or never (manual only). A notification appears when an update is available; updates are never installed without confirmation. | + +### Analytics + +When enabled, Stability Matrix sends anonymous usage data to Lykos to help prioritize development. The data collected is minimal: + +- **Package installs** — package name, version, and whether the install succeeded or failed +- **First-time setup** — which package was selected, which recommended models were chosen, and whether setup was skipped + +No hardware information, model browsing history, personal data, or API keys are included. Additionally, each app launch sends the Stability Matrix version, OS description, and runtime identifier to the analytics API at most once per day. + +This setting is also presented during first-run setup. Analytics are enabled by default (opt-out); you can change your choice here at any time. + +### Add to Start Menu + +(Windows only) Adds Stability Matrix to the Start Menu for the current user or all users. + +### Maximum Simultaneous Downloads + +Limits the number of concurrent model downloads. Does not apply to package installs. Set to `0` for unlimited. + +### Select New Data Directory + +Change the library location where Stability Matrix stores packages, models, images, and settings. Displays the current path. Changing the path does not move existing data — you must relocate files manually. See [Data Directory](../getting-started/data-directory.md#changing-the-data-directory-later) for further details. + +### Select New Models Folder + +Change the shared models directory independently from the main data directory. Useful for keeping models on a separate drive. + +### App Folders + +Quick-access buttons to open key Stability Matrix folders in your file manager: Application Data directory, Logs, Data directory, Checkpoints (Models) shared directory, and Packages directory. + +### System Settings + +| Setting | Description | +|---|---| +| **Default GPU** | Select which GPU Stability Matrix should prefer for package installs. This influences which PyTorch backend index is automatically selected. | +| **Enable Long Paths** | (Windows only) Enables Windows long path support in the registry to avoid path-length errors with deeply nested package or model folders. | + +### System Information + +Read-only diagnostic information about your hardware: + +- **CPU** — processor model +- **Memory** — total installed and available RAM +- **GPU** — detected graphics cards and VRAM + +--- + +## About + +The About section appears at the bottom of the Settings view. It shows: + +- The Stability Matrix app icon and name +- The current version number (e.g., `Version 2.16.1`) +- A **License and Open Source Notices** button that opens a dialog listing third-party licenses for bundled open-source components + +Tapping the version number repeatedly (7 times) enables hidden debug options in the Settings UI. + +## Debug Options + +When debug mode is enabled, a **Debug Options** section appears in the Settings view. It contains diagnostic tools and utilities intended for development and troubleshooting: + +### Diagnostics + +| Item | Description | +|---|---| +| **Paths** | Displays the current working directory, app directory, base directory, and AppData path. | +| **Compat Info** | Shows platform, portable mode status, library directory state, and other environment details. | +| **GPU Info** | Lists all detected GPUs with their properties. | + +### Utilities + +| Item | Description | +|---|---| +| **Animation Scale** | Adjusts UI animation speed from 0× (instant) to 2×. Lower values make the UI feel snappier during testing. | +| **Notification** | Fires a test in-app notification to verify the notification system. | +| **Content Dialog** | Opens a test content dialog to verify dialog rendering. | +| **Exceptions** | Buttons to trigger unhandled and dispatcher exceptions for testing error handling and crash reporting. | +| **Download Manager tests** | Adds a test tracked download entry. | +| **Refresh Models Index** | Manually refreshes the local model index used by the Checkpoint Manager. | +| **Make image grid** | Opens a file picker to select images and generates a combined grid image. | +| **Image metadata parser** | Chooses an image and parses its metadata for debugging. | +| **Gemini error dialogs** | Previews the various Image Lab / Nano Banana error states (key not configured, invalid key, quota exceeded, access forbidden, generic failure) without triggering a real API call. | + +Additional debug commands may appear dynamically at the bottom of the section.