Configuration scopes and restart behavior

Every setting in SoAI belongs to one scope, and the scope decides both who the change reaches and when it starts applying. A conversation parameter reaches the next message you send, a model parameter reaches every request routed to that model, a plugin configuration reaches one backend process, and a Core configuration change reaches the whole instance, sometimes only after a restart. Configuration explains what each Core key means, Chat documents the chat dialog, and Models catalog documents the parameter form, so this page covers choosing the scope and knowing when the value takes effect.

Choose where to make the change

Skill libraries belong to accounts, and each ordinary chat has its own selection. Import changes the library immediately; Save in Chat configuration > Skills applies the chat selection without a restart. A Skills preset stores references to installed skills, not copies of their contents.

How a model parameter value is resolved

In the SoAI WebUI, open Models and select Edit parameters for an installed model, or open its details and use the Parameters tab, which is the same screen. Both need Model administration (MODEL_ADMIN), and a virtual model uses Edit virtual model instead. The plugin supplies that form, including its fields, accepted values, defaults, categories, and reload rules, and SoAI validates your changes against that definition and stores one set of model defaults shared by every user. The value that reaches the backend is assembled per request from four sources, from lowest to highest priority:

1. The plugin's own parameter default.
2. The custom value saved for the model.
3. A constituent override, when a virtual model routes the request to that model.
4. A value sent by the current chat or API request.

Because the request is applied last, a chat can override a stored model default without changing it. Reset in the parameter form discards your unsaved edits and returns every field to the values the page loaded, so it undoes a change in progress rather than removing a stored one. Deleting the stored custom values so a model falls back to the plugin's own defaults is a separate operation on the model's parameters endpoint, listed in the HTTP API reference.

SoAI splits the resolved values into the parameters a backend reads when it starts a model and the ones it reads per request, and the startup group carries a fingerprint that decides whether a reload is needed. Change a parameter marked REQUIRES RELOAD and a model that is already loaded moves to Ready (modified) once the request in flight finishes, so the next request for that model reloads it with the new startup values before dispatch, while an unloaded model picks them up the next time it loads. Save confirms storage rather than the reload, so watch the state on the model detail or Plugins page.

What a plugin configuration save changes

Open Plugins, find the plugin or clone, and select Edit configuration, which appears only when the plugin declares managed configuration support and no other operation currently holds its card. You need Configuration changes (CONFIG_PATCH). SoAI builds the form from the stored configuration, so a boolean becomes a toggle, a scalar becomes a text or number field, and a list or object becomes a JSON editor whose contents must parse as the matching type. A plugin that supports GPU binding also gets a device selector, and the devices you pick are checked against the GPUs SoAI detects at the moment you save. Each installed plugin and each clone keeps its own configuration file, so a clone is configured independently of the original.

Saving writes that file first, then hands the new values to the plugin: a loaded plugin replaces its in-memory configuration in place, and a plugin that is not loaded is left alone and reads the file the next time it starts. Nothing stops or reloads a running backend, so a value the backend process read when it launched, such as its host, port, model directories, or GPU binding, keeps the old value until you stop and start that plugin yourself. The Configuration for <plugin> saved successfully notification confirms the write rather than the effect. Installation, cloning, remote providers, and backend updates belong in Install and manage plugins.

Core configuration saves and pending restarts

Select the Settings button at the right of the header, choose Settings, then select Advanced in the page header, which requires an administrator with Configuration changes (CONFIG_PATCH). Configuration lists every key, its default, and its own per-setting Requires restart column, so what follows is what happens after you select Save.

The WebUI sends only the fields you changed, and SoAI merges them into the active configuration, validates the merged result, and leaves the current configuration in place when validation fails. A value whose name marks it as sensitive comes back to the form as ***REDACTED***, and leaving that placeholder alone drops the field from the request, so the stored secret survives the save instead of being overwritten by the placeholder text.

SoAI then compares the previous and new configuration by area rather than by individual key, grouping SYSTEM, SERVER, MODELS, TOOLS, DATA, INTEGRATIONS, and OBSERVABILITY two levels deep, API three levels deep, and PLUGINS and AUTOMATION at the top level. Three of those areas can be applied to the running process: SYSTEM.RUNTIME, API.OPENAI.RATE_LIMITING, and MODELS.ROUTING. A save whose changed areas all fall inside those three takes effect without a restart, while a change touching anything else records a pending restart, and one Save can contain both kinds.

Some settings inside the reloadable areas are exceptions, because SoAI reads them once while it starts. Everything under MODELS.ROUTING.HTTP_CLIENT_LIMITS and everything under MODELS.ROUTING.HTTP_CLIENT_TIMEOUTS is compared against the values the process started with rather than against the previous save, so a change there records a pending restart and restoring the original values clears it again. MODELS.ROUTING.HTTP_CLIENT_TRUST_ENV is read once beside them but takes no part in that comparison, so it reports nothing and needs a restart you ask for yourself, and several admission and queue settings under MODELS.ROUTING behave the same way. Scheduler and runtime tuning lists them.

Reloading the rate-limiting area rebuilds the limiter and resets its in-memory windows, so review Rate limits and quotas before changing an instance-wide policy.

When a save leaves anything pending, the WebUI keeps a Restart SoAI to apply pending changes notification until the process restarts with the saved file. Select Restart SoAI in that notification when you are ready, which requires System power control (SYSTEM_POWER).

Settings that do not live in the configuration file

Not everything under Settings is Core configuration. The instance name is stored in the system database: select the Settings button at the right of the header, choose Settings, select General, find Instance, enter an Instance name, then select Save in the page header. It accepts up to 64 characters, a blank value clears it, and the change applies without a restart. SoAI uses the name on health and discovery surfaces, the Instance ID beside it is generated and read only, and the whole section appears only to administrators with Configuration changes (CONFIG_PATCH).

Related documentation

• Skills
• Configuration
• Chat
• Models catalog
• Install and manage plugins
• Personal preferences
• Security hardening