Plugins provide the backend behind each local engine or remote provider. In the SoAI WebUI, use Plugins for backend installation, updates, configuration, cloning, and health checks. Use Models to add, download, inspect, enable, or remove the model entries served through those plugins.
Access to plugin and model controls
Opening Plugins requires Plugin read access (PLUGIN_READ), and opening
Models requires Model read access (MODEL_READ). Backend installation,
updates, cloning, deletion, and related plugin controls require Plugin administration
(PLUGIN_ADMIN). Model downloads and deletion require Model administration
(MODEL_ADMIN). Editing a plugin configuration or a capacity setting also requires
Configuration changes (CONFIG_PATCH). Administrators receive these actions by default;
see Administration overview to manage exceptions in ACL.
Install and update a local backend
Open Plugins and select the plugin you want to use. When its status is Backend not installed, select Install backend. In the backend dialog, choose a backend variant that is available for the host, review its compatibility message, and select Start installation. Installation progress remains visible in the dialog. When it finishes, open Models > Add model to search for, download, or register a model for that plugin.
To maintain an installed backend, select Manage backend on its plugin card. Use Check for updates, then select Update only when an update is offered. Select Uninstall to remove the managed runtime. The WebUI confirms that model files are preserved during backend uninstallation, so remove models separately from Models when that is what you intend.
External providers are different: they do not have a local backend to install. Add one through Models > Add model > Add provider, choose External, and enter the Provider name, API URL, API key, and optional Models filter. SoAI discovers models from the provider after the connection is saved.
The variant selector shows compatibility guidance for your devices and drivers. Auto excludes variants with unmet requirements and keeps your GPU binding. Choose different devices or another runtime when needed. If compatibility is unknown, check the reported cause; installation and launch still validate requirements. Choosing an explicit variant does not bypass those checks.
Backend update availability and automatic updates
SoAI checks eligible installed backends for updates. Use Check for updates to check the selected plugin. A failed or unavailable check does not mean it is up to date; resolve the reported problem and retry.
A confirmed update appears as a blue Update available badge. Select Update backend when your permissions and the plugin's state allow it. The Plugins sidebar indicator and Updates page also identify available updates. Open Plugins to follow progress.
Automatic updates for built-in backends are enabled by default through
PLUGINS.BACKEND_UPDATES.AUTO_UPDATE_BUILTIN.
They require online mode, an enabled compatible plugin, and a stopped, idle backend. SoAI waits rather than stopping
inference. Third-party backends need manual updates. Each built-in plugin package receives at most one automatic
attempt; after failure or cancellation, review the result and retry manually. Turning the setting off prevents
future automatic updates; an update already running continues to its final result.
After cancelling a backend operation in Tasks, wait for its final result before retrying. An installation that has already completed may report success. If a MeloTTS container operation reports a cleanup failure, restore access to the Docker engine and retry. MeloTTS preserves existing voice models and verified downloads for the retry.
Storage reserved by other operations can leave insufficient installation headroom even when the disk has free space. Wait for active installations to finish or free space, then retry.
Saved backend version limits
A plugin can declare MAX_SUPPORTED_BACKEND_VERSION in its defaults. SoAI reapplies that declared value
during installation, application updates, and explicit dependency installation or repair, while preserving your
selected BACKEND_VERSION and other saved settings. This policy includes third-party packages and clones;
packages without the declaration keep their configuration unchanged. Reapplying a limit does not replace a backend,
and backend checks and automatic-update settings still determine whether an update runs.
Edits to the limit remain until the next application installation, update, or explicit dependency repair reapplies the package default. Deleted built-in plugins stay absent through application updates and installation over the existing installation; use Plugins > Add plugin to upload a package or download it from a trusted URL.
Read plugin states
The status badge describes the current backend or runtime condition. Transient states normally resolve on their own; error and compatibility states need an operator decision.
Backend operations
Backend not installed, Backend installing, Backend updating,
Removing backend, and Deleting mean that the plugin is waiting for a runtime, running a
backend operation, or being deleted. Wait for the operation to finish, or open the plugin dialog to inspect its
progress and error message.
Normal lifecycle
Stopped, Starting, Loading, Ready,
Ready (pending dispatch), Ready (modified), Idle,
Processing, and Stopping are normal lifecycle states. No repair is usually needed. A
request can start or load a stopped local backend when routing permits it.
Persistent services
Persistent identifies plugins that stay running rather than being unloaded to make room, such as the
bundled audio services and External provider. Check its capability and capacity requirements before treating it like
an unloadable chat backend.
Errors, quarantine, and incompatibility
Install error, Load error, Update error,
Backend uninstall error, Delete error, Error,
Quarantined, and Incompatible mean an operation or runtime failed, recovery quarantined
the plugin, or the host and plugin do not meet a declared requirement. Read the card's compatibility or error detail,
open Logs, then follow Reset an
open circuit or Make a
quarantined plugin available again for the reported state.
Missing or disabled state
Status unknown, Not detected, Absent, and Disabled mean SoAI
lacks current state data, the plugin is missing, it is absent from its expected location, or it is deliberately
offline. Restore or add a trusted plugin only if it is required, or enable the intended plugin after reviewing its
state.
Clone a plugin
A clone is a separate plugin instance for a plugin that supports cloning. On the plugin card, select Clone plugin. The dialog lets you choose a Custom name and whether to Clone models. Include model files only when you want an additional copy and have enough storage. After the clone exists, select Edit configuration on the original and clone to give them distinct host, port, model-path, or GPU-binding values where those fields are available.
Cloning does not make two model instances fit in memory. Before starting both, review Capacity planning and the hardware data in the WebUI.
Add third-party plugins carefully
Open Plugins and select Add plugin. The dialog offers
Upload plugin, Download plugin from URL, and Add plugin manually.
These controls require Plugin administration (PLUGIN_ADMIN). A plugin can execute code on the SoAI host, so install only a package you trust. If a backend
already offers an OpenAI-compatible API, use the External provider route instead of installing a plugin solely to
proxy it. On Upload plugin, drag a .soaiplugin file onto
Drop a plugin here or select that area to choose one, then select Upload plugin.
The manual tab displays the plugin folder, offers Open Files, and shows Restart
after you place a .soaiplugin file there. SoAI loads that manually placed plugin after the restart.