Plugins overview

SoAI connects local engines and remote providers through .soaiplugin packages. A plugin declares its supported operations, manages any backend it owns, and supplies models to the shared catalog. The WebUI presents those declarations as the actions and capability badges on each plugin and model.

For reusable assistant instructions, templates, or task procedures, use skills. A skill can guide tools already available in a conversation; a plugin connects an engine or provider and can manage its backend. See Creating a skill if your task needs instructions rather than a backend integration.

Bundled plugins

Plugin Role
CTranslate2 Offline CPU neural machine translation.
External A connector for OpenAI-compatible APIs.
Llama.cpp A llama.cpp backend.
Llama.cpp Embeddings A llama.cpp backend dedicated to embeddings.
Melo TTS A frozen MeloTTS text-to-speech backend.
Ollama An Ollama backend and Ollama Cloud provider.
vLLM A vLLM backend.
Whisper An OpenAI Whisper speech-to-text backend.

The bundled package metadata is the source for these descriptions. Read Bundled plugins reference before choosing a backend, since a plugin's capabilities and the capabilities of an individual model are separate.

Add a plugin in the SoAI WebUI

Opening Plugins requires Plugin read access (PLUGIN_READ). Installing or changing a package requires the Administrator-only Plugin administration (PLUGIN_ADMIN) action. A plugin can execute code under the SoAI service account, so inspect its source and license before adding it.

  1. Open Plugins and select Add plugin.
  2. Select Download plugin from URL, enter the Plugin URL, and select Download plugin; or select Upload plugin, choose a .soaiplugin file, and select Upload plugin.
  3. Keep the dialog open to review progress, or open the Tasks panel in the header. Wait for a terminal result before using the new card.

The server rejects uploads when PLUGINS.FEATURES.UPLOADS is disabled and URL downloads when PLUGINS.FEATURES.DOWNLOADS is disabled. A URL download is also rejected in offline mode. The tabs can still be visible, so a rejected operation means the administrator must change the relevant setting or use an allowed installation method.

To change either transfer setting, select the Settings button at the right of the header, then select Settings from its menu. Select Advanced in the page header, select the Plugins tab and Features group, change Uploads or Downloads, then select Save. Advanced requires an Administrator with Configuration changes (CONFIG_PATCH).

Add plugin manually appears only for an Administrator account. It shows the configured plugins folder and provides Copy, Open Files, and Restart. Place the package in the shown folder, then use Restart; manually placed packages are discovered after the application restarts.

Read the actions on a plugin card

Control When it appears or succeeds
Clone plugin The plugin supports cloning, is enabled, and is not locked. Cloning also requires Plugin administration (PLUGIN_ADMIN).
Edit configuration The plugin declares configuration support and is not locked by an active operation. Saving configuration requires Configuration changes (CONFIG_PATCH).
Install backend The plugin supports backend installation, is not permanently disabled or waiting for a compatibility override, and its status is Backend not installed or Install error.
Manage backend The plugin declares backend management support. Backend mutations require Plugin administration (PLUGIN_ADMIN) and a compatible plugin with the required system capabilities.
Stop plugin The current runtime state is stoppable. Persistent plugins are not stoppable from this control.

The card exposes only what the plugin and its current state support. For model download, provider, cloning, and backend-maintenance procedures, see Install and manage plugins.

Package and worker boundary

Before activating a package, SoAI audits its archive, reads its literal manifest, validates declared package dependencies, prepares the package and its Python environment, then starts a dedicated worker process. With PLUGINS.SECURITY.SAFETY_VALIDATION enabled, package safety validation also checks source imports. The host talks to the worker through authenticated IPC. The worker boundary separates runtime state, but it is not an operating-system sandbox: package code retains the permissions of the account running SoAI.

Related documentation