Configuration

By default, SoAI stores its active Core configuration in data/config/config.yaml, relative to the install root. SOAI_CONFIG_PATH selects another path when set; a relative value is resolved from the install root. Model parameters live in the database. Each plugin keeps its own plugins/<name>.soaiplugin.yaml sidecar, so neither belongs to the Core reference below.

Change settings in the SoAI WebUI

  1. Select the Settings button at the right of the header, then choose Settings.
  2. Select Advanced in the page header.
  3. Choose the tab for the first path segment, edit the field, and select Save.
  4. If SoAI shows a restart notice, select Restart SoAI when you are ready to apply the pending values.

The WebUI renders path segments as sentence-case labels: SYSTEM appears as the System tab and API appears as Api. Middle segments name groups, and the last segment names the field. For example, SYSTEM.IPC.MAX_MESSAGE_BYTES is under System, then IPC, as Max message bytes.

Search settings... finds a field by that final label or by the configuration key itself. Searching SYSTEM.IPC.MAX_MESSAGE_BYTES filters the form down to that one field and opens the tab holding it. Typing only the end of a key, or its segments spaced out instead of dotted, matches the same field.

The search in the header accepts those keys anywhere in the WebUI. It lists a matching key under Configuration, and selecting the result opens Settings with that field already filtered. Configuration keys appear in these results only for administrators with the Configuration changes (CONFIG_PATCH) permission.

You need an administrator account with the Configuration changes (CONFIG_PATCH) permission. Fix any field errors shown in the form before selecting Save. The WebUI sends the changed values to the Core configuration endpoint.

The Advanced form does not display settings whose value is an empty object. Edit these four entries in config.yaml when you need them:

  • API.OPENAI.RATE_LIMITING.ROUTERS
  • MODELS.ROUTING.OWNER_RUNNING_LIMITS.PER_OWNER_TYPE
  • MODELS.ROUTING.HEALTH_CHECKS.MAX_CONCURRENT_TASKS_PER_PLUGIN.PER_PLUGIN
  • TOOLS.MCP.BROWSER.PROFILES

What config.default.yaml contains

data/config/config.default.yaml is a generated snapshot of the current code-first V1 schema. SoAI creates or replaces it when the file is missing or no longer matches that schema. The file records factory defaults for comparison and startup recovery. During stage-zero startup, SoAI copies this file when the active configuration is missing. Full bootstrap can also rebuild the active file from the same code schema. Do not edit config.default.yaml; SoAI replaces changes that do not match the current schema.

Reset configuration

Select the Settings button at the right of the header, choose Settings, select Reset, find Configuration, then select Reset to discard the active Core configuration and restart with factory defaults. This action requires an administrator account with the Configuration changes (CONFIG_PATCH) permission. It preserves users, conversations, files, models, plugins, backups, and user preferences. The WebUI reset accepts only managed configuration files inside the installation. If SOAI_CONFIG_PATH points outside the installation, host system actions are disabled, or the WebUI cannot load, follow the manual procedure in Reset.

Direct editing and alternate paths

Stop SoAI before editing config.yaml by hand, then start it after saving the file. Set SOAI_CONFIG_PATH before launch if the active file must live elsewhere. Relative values are resolved from the install root. On startup, SoAI validates the YAML and reconciles it with the current V1 schema. Use the WebUI for routine changes so field errors are shown before you save.

Configuration reference

This reference lists every terminal setting supported by the current Core V1 configuration, including empty configurable objects. The defaults below are factory values, not values read from the local active configuration. Requires restart reports whether a change must wait for a SoAI process restart before it is fully applied. Configuration links elsewhere in the documentation open the matching row.

SYSTEM

Setting Type Description Factory default Requires restart
SYSTEM.PATHS.BASE String Base directory used to resolve SoAI's relative data paths. An empty value uses the installation directory. "" Yes
SYSTEM.PATHS.SYSTEM_DATA String Directory for SoAI-managed application data, resolved under the configured base path. "data" Yes
SYSTEM.PATHS.TEMP String Directory for temporary files created by SoAI, resolved under the system data directory. "temp" Yes
SYSTEM.PATHS.LOCKS String Directory for process and resource lock files, resolved under the system data directory. "locks" Yes
SYSTEM.PATHS.SYSTEM_ENCRYPTION_KEY String Key file used to encrypt protected values, resolved under the system data directory. "secret.key" Yes
SYSTEM.RUNTIME.STAY_OFFLINE Boolean Keeps SoAI from using network-dependent startup and runtime features when enabled. false No
SYSTEM.RUNTIME.HOST_SYSTEM_ACTIONS_DISABLED Boolean Prevents SoAI from issuing host shutdown, restart, and similar system actions. false No
SYSTEM.RUNTIME.HARDWARE_MUTATION_DISABLED Boolean Makes hardware controls read-only, including GPU power, clock, and fan changes. false No
SYSTEM.RUNTIME.STARTUP_BEEP Boolean Plays two short tones after SoAI finishes starting: through the PC speaker on Linux (requires the pcspkr driver and root or CAP_SYS_TTY_CONFIG) and at low volume through the default audio device on Windows. true Yes
SYSTEM.SECURITY.BLOCK_PRIVATE_NETWORK_EGRESS Boolean Blocks protected outbound requests whose resolved destination is a private network address. false Yes
SYSTEM.SECURITY.DNS_VALIDATION_TIMEOUT_SEC Number A security-related DNS lookup must finish within this many seconds. 3.0 Yes
SYSTEM.SECURITY.DNS_OVERRIDE_SERVERS String Comma-separated DNS servers used by guarded outbound requests. Empty uses the host resolver. "" Yes
SYSTEM.CONFIG.POLLING_INTERVAL_MS Integer Interval, in milliseconds, between checks for changes to the active configuration file. 60000 Yes
SYSTEM.IPC.MAX_MESSAGE_BYTES Integer SoAI rejects an internal process communication message larger than this many bytes. 268435456 Yes
SYSTEM.SHUTDOWN.QUIESCE_PERIOD_SEC Integer Graceful shutdown pauses for this many seconds while new work stops arriving. 3 Yes
SYSTEM.SHUTDOWN.SERVER_DRAIN_TIMEOUT_SEC Integer Active server requests have this many seconds to finish during shutdown. 10 Yes
SYSTEM.SHUTDOWN.COMPONENT_TIMEOUT_SEC Integer Default shutdown deadline, in seconds, for components without a more specific limit. 20 Yes
SYSTEM.SHUTDOWN.TASK_REGISTRY_TIMEOUT_SEC Integer Registered background tasks have this many seconds to finish during shutdown. 150 Yes
SYSTEM.SHUTDOWN.ORCHESTRATOR_TIMEOUT_SEC Integer During shutdown, SoAI waits this many seconds for the model orchestrator to stop. 75 Yes
SYSTEM.SHUTDOWN.MCP_TIMEOUT_SEC Integer During shutdown, SoAI waits this many seconds for the MCP runtime to stop. 60 Yes
SYSTEM.SHUTDOWN.FINALIZER_TIMEOUT_SEC Integer Final shutdown callbacks must complete within this many seconds. 10 Yes
SYSTEM.SHUTDOWN.FORCE_CLEANUP_TIMEOUT_SEC Integer After normal shutdown deadlines expire, forced cleanup may run for this many seconds. 5 Yes
SYSTEM.SHUTDOWN.WATCHDOG_TIMEOUT_SEC Integer If shutdown exceeds this many seconds, the watchdog treats it as stuck. 1050 Yes
SYSTEM.UPDATER.TIMEOUT_SEC Integer Connection and routine request timeout, in seconds, used by the software updater. 10 Yes
SYSTEM.UPDATER.API_TIMEOUT_SEC Integer The updater stops waiting for release information after this many seconds. 30 Yes
SYSTEM.UPDATER.DOWNLOAD_TIMEOUT_SEC Integer An update archive download must finish within this many seconds. 3600 Yes
SYSTEM.UPDATER.STREAM_TIMEOUT_SEC Integer A long-running updater stream must finish within this many seconds. 7200 Yes
SYSTEM.UPDATER.POST_UPDATE_HOOK_TIMEOUT_SEC Integer Post-update installation hooks get this many seconds to finish. 7200 Yes
SYSTEM.UPDATER.MAX_ARCHIVE_MB Integer The updater rejects an update archive larger than this many megabytes. 2048 Yes
SYSTEM.HARDWARE.ENABLED Boolean Enables hardware discovery, monitoring, history, and supported device controls. true Yes
SYSTEM.HARDWARE.GPU_SETTINGS_SLOTS_PATH String File for reusable GPU settings slots, resolved under the system data directory. "gpu/gpu_settings_slots.json" Yes
SYSTEM.HARDWARE.DISK_FREE_SPACE_TOLERANCE_MB Integer Safety margin, in megabytes, retained when SoAI evaluates available disk space. 750 Yes
SYSTEM.HARDWARE.DISK_RESERVATION_LOCK_TIMEOUT_SEC Number A disk reservation waits this many seconds to acquire its lock. 10.0 Yes
SYSTEM.HARDWARE.MONITORING_INTERVAL_MS Integer Interval, in milliseconds, between live hardware metric samples. 3000 Yes
SYSTEM.HARDWARE.HARDWARE_CACHE_TTL Integer SoAI reuses a general hardware snapshot for this many seconds before refreshing it. 2 Yes
SYSTEM.HARDWARE.DETAILED_GPU_INFO Boolean Collects detailed GPU properties in addition to basic utilization and memory data. true Yes
SYSTEM.HARDWARE.HARDWARE_HISTORY_ENABLED Boolean Stores hardware metric samples for historical charts and queries. true Yes
SYSTEM.HARDWARE.DB_RETENTION_HOURS Integer Number of hours hardware history remains in the database. 168 Yes
SYSTEM.HARDWARE.VARIANT_SPEED_TEMPLATES_REQUIRE_MEASUREMENTS Boolean Requires measured performance data before generating model variant speed templates. true Yes
SYSTEM.HARDWARE.GPU_INFO_CACHE_TTL_SEC Integer SoAI caches detailed GPU information for this many seconds. 1 Yes
SYSTEM.HARDWARE.NETWORK_SPEED_CACHE_TTL_SEC Integer SoAI caches measured network speed for this many seconds. 5 Yes
SYSTEM.HARDWARE.GPU_VENDOR_CACHE_TTL_SEC Integer SoAI caches the detected GPU vendor for this many seconds. 60 Yes
SYSTEM.HARDWARE.MINIMUM_SPECS_WARNING_ENABLED Boolean Shows a warning when the host falls below SoAI's minimum hardware guidance. true Yes
SYSTEM.TASKS.CANCELLATION_HISTORY_LIMIT Integer The in-memory history keeps this many recent task cancellation records. 2048 Yes
SYSTEM.TASKS.CANCELLATION_LISTENER_QUEUE_SIZE Integer Capacity of each task cancellation listener queue. 1 Yes
SYSTEM.TASKS.DEFAULT_TTL_SECONDS Integer Default lifetime, in seconds, assigned to tasks without an explicit expiry. 3600 Yes
SYSTEM.TASKS.CLEANUP_INTERVAL_SECONDS Integer Interval, in seconds, between task registry cleanup passes. 300 Yes
SYSTEM.TASKS.MEMORY_CACHE_MAX_SIZE Integer The in-memory cache keeps up to this many task records. 10000 Yes
SYSTEM.TASKS.TERMINAL_CACHE_GRACE_SECONDS Integer The fast cache keeps a completed, failed, or cancelled task for this many seconds. 60 Yes
SYSTEM.TASKS.STUCK_TASK_TIMEOUT_SECONDS Integer SoAI marks a running task as stuck if it has not finished after this many seconds. 3600 Yes
SYSTEM.TASKS.MAX_CONCURRENT_PER_OWNER Integer One task owner may have this many active tasks. 100 Yes
SYSTEM.TASKS.MAX_CONCURRENT_PER_HTTP_REQUEST Integer One HTTP request may have this many active tasks. 100 Yes
SYSTEM.TASKS.MAX_CONCURRENT_PER_SYSTEM Integer One system operation may have this many active tasks. 100 Yes
SYSTEM.TASKS.MAX_CONCURRENT_PER_CONVERSATION Integer One conversation may have this many active tasks. 100 Yes
SYSTEM.TASKS.TASK_LIST_MAX_LIMIT Integer A task-list query may request at most this many tasks per page. 1000 Yes
SYSTEM.TASKS.TASK_LIST_MAX_OFFSET Integer Task-list pagination accepts offsets up to this value. 10000 Yes
SYSTEM.TASKS.ACTIVE_TASKS_LIMIT Integer A task status snapshot returns up to this many active task records. 1000 Yes
SYSTEM.EVENT_BUS.QUEUE_SIZE Integer The in-memory event bus queue holds up to this many waiting events. 10000 Yes
SYSTEM.EVENT_BUS.NUM_WORKERS Integer Number of workers that dispatch queued in-memory events. 8 Yes
SYSTEM.EVENT_BUS.PUBLISH_TIMEOUT_SEC Number A publisher waits this many seconds to place an event on a full queue. 0.25 Yes
SYSTEM.EVENT_BUS.BACKPRESSURE_WARNING_DEPTH Boolean Queue depth that triggers a backpressure warning. False disables the warning threshold. false Yes
SYSTEM.EVENT_BUS.DISPATCH_TIMEOUT_SEC Number Overall deadline, in seconds, for dispatching one event to its subscribers. 30.0 Yes
SYSTEM.EVENT_BUS.PER_CALLBACK_TIMEOUT_SEC Number Each in-memory event subscriber callback gets this many seconds to finish. 5.0 Yes
SYSTEM.EVENT_BUS.SHUTDOWN_TIMEOUT_SEC Number Event bus workers get this many seconds to stop during shutdown. 10.0 Yes
SYSTEM.EVENT_BUS.DOMAIN.OUTBOX.POLL_INTERVAL_SEC Number Interval, in seconds, between durable domain-event outbox polls. 0.25 Yes
SYSTEM.EVENT_BUS.DOMAIN.OUTBOX.BATCH_LIMIT Integer One poll claims up to this many domain events from the durable outbox. 100 Yes
SYSTEM.EVENT_BUS.DOMAIN.OUTBOX.PROCESSING_TIMEOUT_SEC Number A worker gets this many seconds to process one claimed outbox batch. 10.0 Yes
SYSTEM.EVENT_BUS.DOMAIN.OUTBOX.QUARANTINE_DELAY_SEC Integer Delay, in seconds, before quarantined domain events become eligible for another attempt. 86400 Yes
SYSTEM.EVENT_BUS.DOMAIN.OUTBOX.SUPERVISOR_RESTART_INITIAL_SEC Number Initial delay, in seconds, before restarting a failed outbox worker. 0.5 Yes
SYSTEM.EVENT_BUS.DOMAIN.OUTBOX.SUPERVISOR_RESTART_MAX_SEC Number Repeated outbox worker failures increase the restart delay up to this many seconds. 30.0 Yes
SYSTEM.EVENT_BUS.DOMAIN.OUTBOX.SUPERVISOR_RESTART_JITTER_SEC Number Outbox worker restart delays receive up to this many seconds of random jitter. 0.5 Yes
SYSTEM.EVENT_BUS.DOMAIN.DELIVERY.DEFAULT_TIMEOUT_SEC Number Default durable event delivery deadline in seconds. Zero leaves delivery without an overall deadline. 0.0 Yes
SYSTEM.EVENT_BUS.DOMAIN.DELIVERY.PER_CALLBACK_TIMEOUT_SEC Number Each durable domain-event subscriber callback gets this many seconds to finish. 30.0 Yes
SYSTEM.INACTIVITY.CHECK_INTERVAL_SEC Integer Interval, in seconds, between checks for system and model inactivity. 15 Yes
SYSTEM.INACTIVITY.SYSTEM.ENABLED Boolean Enables the configured host action after system-wide inactivity. false Yes
SYSTEM.INACTIVITY.SYSTEM.TIMEOUT_MINUTES Integer Minutes without qualifying activity before the configured system action runs. 30 Yes
SYSTEM.INACTIVITY.SYSTEM.ACTION String Action performed after system inactivity. Accepted values are shutdown and unload_models. "shutdown" Yes
SYSTEM.INACTIVITY.MODELS.ENABLED Boolean Enables automatic unloading of models that remain inactive. false Yes
SYSTEM.INACTIVITY.MODELS.TIMEOUT_MINUTES Integer Minutes a loaded model may remain unused before SoAI unloads it. 10 Yes

SERVER

Setting Type Description Factory default Requires restart
SERVER.PUBLIC_ORIGIN String Externally reachable HTTPS origin used for OAuth and messaging callback URLs. Those features reject an empty value. "" Yes
SERVER.HTTP.ENABLED Boolean Starts the HTTP API server when SoAI launches. true Yes
SERVER.HTTP.LOG_STREAM.TIMEOUT_SEC Integer A log-stream request returns after waiting this many seconds for new records. 30 Yes
SERVER.HTTP.LOG_STREAM.BATCH_SIZE Integer One log-stream batch contains up to this many records. 50 Yes
SERVER.HTTP.LOG_STREAM.INTERVAL_MS Integer Minimum interval, in milliseconds, between log-stream batches. 200 Yes
SERVER.HTTP.NETWORK.HOST String Network address on which the main HTTP server listens. "0.0.0.0" Yes
SERVER.HTTP.NETWORK.PORT Integer TCP port on which the main HTTP server listens. 5090 Yes
SERVER.HTTP.NETWORK.DISCOVERY_HOST String Network address advertised or bound for SoAI service discovery. "0.0.0.0" Yes
SERVER.HTTP.NETWORK.SHUTDOWN_TIMEOUT_SEC Integer The HTTP server gets this many seconds to stop during shutdown. 10 Yes
SERVER.HTTP.CORS.ALLOWED_ORIGINS List Browser origins allowed to call the API across origins. Empty permits none; an entry of * permits all. [] Yes
SERVER.HTTP.CORS.ALLOW_CREDENTIALS Boolean The server accepts credentialed cross-origin requests when the allowed origins contain an origin or the wildcard. true Yes
SERVER.HTTP.CORS.MAX_AGE_SEC Integer Browsers may cache a successful CORS preflight response for this many seconds. 3600 Yes
SERVER.HTTP.PROXY.ENABLE_HEADERS Boolean Trusts supported forwarded request headers when the immediate proxy is trusted. false Yes
SERVER.HTTP.PROXY.TRUSTED_NETWORKS List IP networks whose reverse proxies may supply trusted forwarded headers. [] Yes
SERVER.HTTP.ACCESS_CONTROL.IP_WHITELIST List Client IP addresses or networks allowed to reach the HTTP server. Empty allows all. [] Yes
SERVER.HTTP.ACCESS_CONTROL.IP_BLACKLIST List Client IP addresses or networks denied access to the HTTP server. [] Yes
SERVER.HTTP.SSL.TLS_ENABLED Boolean Serves the main HTTP endpoint over TLS using the configured certificate and key. false Yes
SERVER.HTTP.SSL.CERT_FILE String Path to the PEM certificate chain used by the HTTP server. "" Yes
SERVER.HTTP.SSL.KEY_FILE String Path to the PEM private key used by the HTTP server. "" Yes
SERVER.HTTP.SSL.CA_FILE String Optional path to a CA certificate bundle used by the TLS configuration. "" Yes
SERVER.HTTP.SSL.KEY_PASSWORD String Password for an encrypted TLS private key. Leave empty for an unencrypted key. "" Yes
SERVER.HTTP.SECURITY.REQUIRE_SECURE_TRANSPORT Boolean Rejects requests that are not recognized as HTTPS, including trusted proxy transport metadata. false Yes
SERVER.HTTP.SECURITY.FORCE_HTTPS_REDIRECT Boolean Redirects eligible HTTP requests to HTTPS instead of serving them over HTTP. false Yes
SERVER.HTTP.SECURITY.ENFORCE_HSTS Boolean Adds the HTTP Strict Transport Security header to secure responses. true Yes
SERVER.HTTP.SECURITY.ENFORCE_UPGRADE_INSECURE_REQUESTS Boolean Adds a content security policy instructing browsers to upgrade insecure subresource requests. false Yes
SERVER.HTTP.REQUEST_BODY.OPENAI_MAX_BYTES Integer OpenAI-compatible and Anthropic-compatible endpoints reject a request body larger than this many bytes. 268435456 Yes
SERVER.HTTP.REQUEST_BODY.NATIVE_MAX_BYTES Integer SoAI-native endpoints reject a request body larger than this many bytes. 16777216 Yes
SERVER.HTTP.REQUEST_BODY.READ_DEADLINE_SEC Number Time allowed, in seconds, to receive an ordinary HTTP request body. For streaming multipart uploads, this limits each wait for more data rather than the total upload time. 120.0 Yes
SERVER.HTTP.STREAMING.STREAM_INACTIVITY_TIMEOUT_SEC Number SoAI closes a response stream after it produces no data for this many seconds. 300.0 Yes
SERVER.HTTP.STREAMING.REPLAY_BUFFER_SIZE Integer The replay buffer keeps this many events for reconnecting stream clients. 1000 Yes
SERVER.HTTP.STREAMING.POST_TERMINAL_CHANNEL_RETENTION_SEC Number SoAI keeps a completed stream channel available to late readers for this many seconds. 300.0 Yes
SERVER.HTTP.STREAMING.RESPONSES_PERSIST_FLUSH_INTERVAL_MS Integer SoAI waits no more than this many milliseconds between database flushes of persisted Responses API events. 100 Yes
SERVER.HTTP.STREAMING.RESPONSES_PERSIST_MAX_EVENTS_PER_FLUSH Integer One persistence batch writes up to this many Responses API stream events. 250 Yes
SERVER.HTTP.STREAMING.RESPONSES_PERSIST_MAX_PENDING_EVENTS Integer The persistence queue holds up to this many unwritten Responses API stream events in memory. 5000 Yes
SERVER.WEBUI.ENABLED Boolean Serves the SoAI WebUI from the HTTP server. true Yes
SERVER.WEBUI.PATH String Primary WebUI static-file directory, resolved under the SoAI installation directory. "frontend" Yes
SERVER.WEBUI.FALLBACK_PATHS List Additional static directories checked when a WebUI asset is absent from the primary path. [] Yes
SERVER.WEBUI.ACCESS_TOKEN_EXPIRE_MINUTES Integer Lifetime, in minutes, of WebUI access tokens. 43200 Yes
SERVER.WEBUI.COOKIE_SECURE Boolean Marks WebUI authentication cookies as HTTPS-only. false Yes
SERVER.WEBUI.WALLPAPER_MAX_SIZE_MB Integer The WebUI rejects a wallpaper file larger than this many megabytes. 25 Yes
SERVER.WEBUI.WALLPAPER_STORAGE_PATH String Wallpaper storage directory, resolved under the system data directory. "wallpaper" Yes
SERVER.WEBUI.WALLPAPER_DOWNLOAD.BLOCK_PRIVATE_NETWORKS Boolean Rejects wallpaper download URLs that resolve to private network addresses. true Yes
SERVER.WEBUI.WALLPAPER_DOWNLOAD.DNS_TIMEOUT_SEC Number Wallpaper downloads stop if host resolution takes more than this many seconds. 3.0 Yes
SERVER.WEBUI.WALLPAPER_DOWNLOAD.MAX_REDIRECTS Integer A wallpaper download follows at most this many redirects. 10 Yes
SERVER.WEBUI.MEDIA_PREVIEWS.CACHE_STORAGE_PATH String Media preview cache directory, resolved under the system data directory. "webui_media_previews_cache" Yes
SERVER.WEBUI.MEDIA_PREVIEWS.MAX_FETCH_SIZE_MB Integer Preview generation will not fetch a remote media file larger than this many megabytes. 100 Yes
SERVER.WEBUI.MEDIA_PREVIEWS.CACHE_MAX_SIZE_MB Integer The media preview cache may use this many megabytes of disk space. 200 Yes
SERVER.WEBUI.MEDIA_PREVIEWS.MAX_REDIRECTS Integer A remote media fetch for a preview follows at most this many redirects. 10 Yes
SERVER.WEBUI.MEDIA_PREVIEWS.TIMEOUT_SEC Number A remote media fetch for a preview must finish within this many seconds. 30.0 Yes
SERVER.WEBUI.MEDIA_PREVIEWS.DNS_TIMEOUT_SEC Number Preview generation stops if remote host resolution exceeds this many seconds. 3.0 Yes
SERVER.WEBUI.MEDIA_PREVIEWS.BLOCK_PRIVATE_NETWORKS Boolean Rejects preview URLs that resolve to private network addresses. true Yes
SERVER.WEBUI.MEDIA_PREVIEWS.TEXT_PREVIEW_MAX_BYTES Integer An inline text preview reads up to this many bytes from the source file. 32768 Yes
SERVER.WEBUI.MEDIA_PREVIEWS.PREVIEW_CLIENT_CACHE_TTL_SEC Integer Browsers may cache a generated media preview for this many seconds. 31536000 Yes
SERVER.WEBUI.AUTO_OPEN_BROWSER Boolean Opens the WebUI in the default browser after a local interactive launch. true Yes
SERVER.WEBUI.NOTIFICATIONS.EMIT_ON_AUTOMATION_COMPLETE Boolean Creates a WebUI notification when an automation run reaches a terminal state. true Yes
SERVER.WEBUI.NOTIFICATIONS.MAX_PER_USER Integer The WebUI keeps up to this many stored notifications for each user. 1000 Yes
SERVER.WEBUI.TERMINAL.ENABLED Boolean Makes the interactive terminal available in the WebUI. true Yes
SERVER.WEBUI.CHAT.CAMERA_VISION_UPLOAD_ENABLED Boolean Allows chat users to capture and upload camera images for vision requests. true Yes
SERVER.WEBUI.CHAT.CAMERA_VISION_IMAGE_OPTIMIZATION_ENABLED Boolean Resizes and re-encodes camera images before sending them to a model. true Yes
SERVER.WEBUI.PROVIDER_TEXT.MAX_STORE_CHARS Integer SoAI stores up to this many extracted characters from one uploaded text document. 2000000 Yes
SERVER.WEBUI.PROVIDER_TEXT.MIN_CHARS Integer Minimum character budget retained when uploaded text is fitted to model context. 20000 Yes
SERVER.WEBUI.PROVIDER_TEXT.CONTEXT_FRACTION Number Fraction of the model context window available to projected uploaded text. 0.3 Yes
SERVER.WEBUI.PROVIDER_TEXT.CHAR_TO_TOKEN_RATIO Integer Estimated source characters per model token when budgeting uploaded text. 4 Yes
SERVER.WEBUI.PROVIDER_TEXT.RESERVED_OUTPUT_TOKENS Integer Model context tokens reserved for the reply when projecting uploaded text. 2048 Yes
SERVER.WEBUI.PROVIDER_TEXT.UPLOAD_PARSE_TIMEOUT_SEC Integer Text extraction from an uploaded document must finish within this many seconds. 120 Yes
SERVER.WEBUI.PROVIDER_IMAGE.MAX_SOURCE_BYTES Integer Provider projection rejects a source image larger than this many bytes. 134217728 Yes
SERVER.WEBUI.PROVIDER_IMAGE.MAX_ENCODED_CHARS Integer SoAI sends at most this many encoded image characters to a model provider. 16777216 Yes
SERVER.WEBUI.PROVIDER_IMAGE.MAX_PIXELS Integer Provider preparation reduces an image until it contains no more than this many pixels. 4000000 Yes
SERVER.WEBUI.PROVIDER_IMAGE.JPEG_QUALITY Integer JPEG quality used when provider image projection requires re-encoding. 85 Yes
SERVER.WEBUI.PROVIDER_VIDEO.MAX_FRAMES_PER_REQUEST Integer SoAI projects up to this many video frames into one model request. 12 Yes
SERVER.WEBUI.PROVIDER_VIDEO.MAX_ENCODED_CHARS_PER_REQUEST Integer One model request may contain at most this many encoded video-frame characters. 16777216 Yes
SERVER.WEBUI.PROVIDER_VIDEO.PROJECTION_TIMEOUT_SEC Integer Video-frame preparation for a provider request must finish within this many seconds. 120 Yes
SERVER.WEBUI.PROVIDER_VIDEO.MAX_CONCURRENT_PROJECTIONS Integer SoAI runs up to this many video projection jobs at the same time. 2 Yes
SERVER.WEBUI.SOAI_LINKS.RESOLVE_MAX_TOKENS Integer Link resolution inspects up to this many link-like tokens in one message. 64 Yes
SERVER.WEBUI.SOAI_LINKS.RESOLVE_MAX_DISTINCT_PATHS Integer Link resolution opens up to this many distinct SoAI file paths from one message. 32 Yes
SERVER.WEBUI.SOAI_LINKS.RESOLVE_CONCURRENT_REQUESTS_PER_CONVERSATION Integer One conversation may run this many link-resolution requests at the same time. 2 Yes
SERVER.WEBUI.SOAI_LINKS.PROJECTION_FOLDER_MAX_ENTRIES Integer A projected SoAI folder includes up to this many directory entries. 20 Yes
SERVER.WEBUI.SOAI_LINKS.PROJECTION_FOLDER_MAX_CHARS Integer A projected SoAI folder description contains up to this many characters. 12000 Yes
SERVER.WEBUI.SOAI_LINKS.PROJECTION_READ_TIMEOUT_SEC Integer Projection stops if reading a linked SoAI file or folder exceeds this many seconds. 30 Yes
SERVER.WEBUI.KNOWLEDGE_LINKS.USE_MAX_ITEMS Integer One WebUI request may attach up to this many knowledge search results. 100 Yes
SERVER.WEBUI.PREVIEW_CONTRACT.MAX_RETRIES Integer The WebUI retries a preview response that violates its contract up to this many times. 2 Yes
SERVER.WEBUI.LOGIN_SECURITY.MAX_BODY_BYTES Integer WebUI login endpoints reject a request body larger than this many bytes. 8192 Yes
SERVER.WEBUI.LOGIN_SECURITY.AUTH_FAILURE_RATELIMIT.WINDOW_SECONDS Integer Rolling window, in seconds, used to count failed WebUI login attempts. 300 Yes
SERVER.WEBUI.LOGIN_SECURITY.AUTH_FAILURE_RATELIMIT.MAX_FAILURES Integer Failed WebUI login attempts allowed in one rate-limit window. 10 Yes
SERVER.WEBUI.LOGIN_SECURITY.ADMIN_ALERTS.ENABLED Boolean Notifies administrators about repeated WebUI authentication failures. true Yes
SERVER.WEBUI.LOGIN_SECURITY.ADMIN_ALERTS.COOLDOWN_SECONDS Integer Minimum seconds between administrator alerts for repeated login failures. 900 Yes

API

Setting Type Description Factory default Requires restart
API.OPENAI.DEFAULT_IMAGE_MODEL_DALLE String Model name used when an OpenAI image request targets the DALL-E generation path without naming a model. "" Yes
API.OPENAI.DEFAULT_IMAGE_MODEL_GPT String Model name used when an OpenAI image request targets the GPT image path without naming a model. "" Yes
API.OPENAI.MAX_FILE_UPLOAD_MB Integer OpenAI-compatible upload endpoints reject a file larger than this many megabytes. 250 Yes
API.OPENAI.TOKEN_COUNTING.APPROXIMATE_SAFETY_RATIO Number Fraction of an estimated context window considered safe when exact token counting is unavailable. 0.85 Yes
API.OPENAI.AGENTIC.COMPACTION.CONTEXT_MARGIN_RATIO Number Fraction of the context window kept free before an agentic conversation is compacted. 0.1 Yes
API.OPENAI.AGENTIC.COMPACTION.POST_COMPACT_MARGIN_RATIO Number Fraction of the context window targeted as free space after compaction. 0.35 Yes
API.OPENAI.AGENTIC.COMPACTION.RESERVED_OUTPUT_TOKENS Integer Tokens held back for the next model reply when compaction budgets the input context. 2048 Yes
API.OPENAI.AGENTIC.COMPACTION.SUMMARY_MAX_TOKENS Integer Maximum output tokens for a conversation compaction summary. The effective limit is also capped at one eighth of the configured context window, leaving room for the summary input. 4096 Yes
API.OPENAI.AGENTIC.MAX_OUTPUT_TOKENS Integer Upper output-token limit applied to agentic model calls. 32768 Yes
API.OPENAI.AGENTIC.DEFAULT_CONTEXT_WINDOW_TOKENS Integer Context window assumed when a selected model does not report one. 65536 Yes
API.OPENAI.AGENTIC.EMPTY_OUTPUT_MAX_RETRIES Integer SoAI makes this many additional attempts after a model returns no usable assistant output. 3 Yes
API.OPENAI.AGENTIC.EMPTY_OUTPUT_SILENT_MAX_RETRIES Integer Number of empty-output retries made without a corrective prompt before later retries ask the model for visible output. 2 Yes
API.OPENAI.AGENTIC.TOOL_RESULT_PROMPT_MAX_CHARS Integer SoAI returns up to this many characters from one tool result to the model. 20000 Yes
API.OPENAI.AGENTIC.TOOL_RESULT_PROMPT_MAX_TOTAL_CHARS_PER_TOOL_BLOCK Integer One contiguous tool-result block contributes up to this many combined characters to the model prompt. 60000 Yes
API.OPENAI.AGENTIC.TOOL_RESULT_PROMPT_MAX_DEPTH Integer Tool-result serialization descends through this many nested object or array levels. 6 Yes
API.OPENAI.AGENTIC.TOOL_RESULT_PROMPT_MAX_ITEMS Integer Tool-result serialization keeps up to this many items from each array. 200 Yes
API.OPENAI.AGENTIC.TOOL_RESULT_PROMPT_MAX_KEYS Integer Tool-result serialization keeps up to this many keys from each object. 200 Yes
API.OPENAI.AGENTIC.TOOL_RESULT_IMAGE_RELAY_MAX_ENCODED_CHARS Integer SoAI relays at most this many encoded tool-result image characters into a model request. 134217728 Yes
API.OPENAI.AGENTIC.TOOL_RESULT_IMAGE_RELAY_MAX_PIXELS Integer Image relay reduces a tool-result image until it contains no more than this many pixels. 4000000 Yes
API.OPENAI.PROMPTS.SOAI_SYSTEM_PROMPT_MODE String Controls SoAI system-prompt injection for eligible SoAI-managed requests: auto follows the conversation toggle, enabled injects regardless of that toggle, and disabled never injects; direct OpenAI-compatible API requests are excluded. "auto" Yes
API.OPENAI.PROMPTS.MESSAGE_COMPATIBILITY_MODE String Selects chat-template role handling: auto, system, system_strict, or user_strict. "auto" Yes
API.OPENAI.RESPONSES.BACKGROUND_MONITOR_MAX_SEC Number SoAI monitors a provider-side background Responses API job for up to this many seconds. 3600.0 Yes
API.OPENAI.KEY_QUOTAS.DEFAULT_COMPLETION_RESERVATION_TOKENS Integer Tokens reserved against an API key quota when the request has no explicit output limit. 512 Yes
API.OPENAI.KEY_QUOTAS.MAX_COMPLETION_RESERVATION_TOKENS Integer SoAI reserves at most this many completion tokens before an API request runs. 32768 Yes
API.OPENAI.KEY_QUOTAS.MIN_TOKEN_RESERVATION_UNITS Integer Smallest billable reservation unit used when converting estimated tokens to quota usage. 1 Yes
API.OPENAI.KEY_QUOTAS.STREAMING_OVERAGE_TOKENS Integer Extra tokens reserved to cover usage that arrives after a streaming quota boundary. 64 Yes
API.OPENAI.KEY_QUOTAS.MAX_HOURLY_WINDOW_HOURS Integer An API key's rolling hourly quota window may span at most this many hours. 720 Yes
API.OPENAI.KEY_QUOTAS.RESERVATION_TTL_SEC Integer Reconciliation expires an unfinished API key quota reservation after this many seconds. 3600 Yes
API.OPENAI.KEY_QUOTAS.RECONCILE_INTERVAL_SEC Integer Interval, in seconds, between cleanup passes for stale quota reservations. 60 Yes
API.OPENAI.KEY_QUOTAS.RECONCILE_BATCH_LIMIT Integer One cleanup pass reconciles up to this many stale quota reservations. 200 Yes
API.OPENAI.RATE_LIMITING.ENABLED Boolean Applies configured request rate limits to registered API routes, including native, MCP, OpenAI-compatible, and Anthropic-compatible routes. false No
API.OPENAI.RATE_LIMITING.DEFAULT_LIMIT String Default rules for registered API routes not classified as streaming, written as amount/unit; an empty string disables this default. "600/minute" No
API.OPENAI.RATE_LIMITING.STREAM_LIMIT String Default rules for registered streaming API routes, written as amount/unit; an empty string disables this default. "60/minute" No
API.OPENAI.RATE_LIMITING.ROUTERS Object Object keyed by registered router name; each router may define DEFAULT_LIMIT, STREAM_LIMIT, PATHS, and STREAM_PATHS overrides. {} No
API.OPENAI.SECURITY.AUTH_FAILURE_RATELIMIT.WINDOW_SECONDS Integer Rolling window, in seconds, used to count failed public-inference API authentication attempts. 60 Yes
API.OPENAI.SECURITY.AUTH_FAILURE_RATELIMIT.MAX_FAILURES Integer Failed public-inference API authentication attempts allowed in one rate-limit window. 5 Yes
API.OPENAI.SECURITY.KEY_EXPIRATION.DEFAULT_TTL_DAYS Integer Default lifetime, in days, assigned to newly created API keys. 90 Yes
API.OPENAI.SECURITY.KEY_EXPIRATION.ROTATION_REMINDER_DAYS Integer Age, in days, at which SoAI reminds an owner to rotate an API key. 75 Yes

MODELS

Setting Type Description Factory default Requires restart
MODELS.CREDENTIALS.GITHUB_TOKEN String GitHub access token used for authenticated model and release downloads that require GitHub. "" Yes
MODELS.CREDENTIALS.HUGGINGFACE_TOKEN String Hugging Face access token used to browse or download gated and private models. "" Yes
MODELS.ROUTING.MAX_CONCURRENT_PLUGINS Integer The scheduler starts or prepares up to this many plugin backends at once for queued inference. 2 No
MODELS.ROUTING.TASK_QUEUE_MAX_SIZE Integer The in-memory scheduling queue holds up to this many inference tasks. 1000 No
MODELS.ROUTING.SCHEDULER_SAFETY_NET_DELAY_SEC Number The scheduler waits this many seconds before rechecking work that received no wake-up signal. 0.5 No
MODELS.ROUTING.DURABLE_QUEUE_LEASE_TTL_SEC Integer Another worker may recover an inference task after its lease has gone unrenewed for this many seconds. 30 No
MODELS.ROUTING.DURABLE_QUEUE_RECOVERY_SWEEP_SEC Integer Interval, in seconds, between checks for expired inference task leases. 5 No
MODELS.ROUTING.DURABLE_QUEUE_HARD_LIMIT_TASKS Integer The durable queue accepts up to this many inference tasks. Zero removes the count limit. 0 No
MODELS.ROUTING.MIN_FREE_DISK_BYTES_FOR_ACCEPT Integer Free disk space, in bytes, required before SoAI accepts another durable inference task. 268435456 No
MODELS.ROUTING.PLUGIN_PREFETCH_WINDOW_DEFAULT Integer Default number of queued tasks a plugin dispatcher may claim ahead of execution. 8 No
MODELS.ROUTING.STANDARD_PRIORITY_AGING_SEC Integer A waiting standard-priority task gains scheduling priority after this many seconds. 25 No
MODELS.ROUTING.FLEX_PRIORITY_AGING_SEC Integer A waiting flex-priority task gains scheduling priority after this many seconds. 120 No
MODELS.ROUTING.CANCEL_ON_CLIENT_DISCONNECT Boolean Cancels inference work when the client that submitted it disconnects. false No
MODELS.ROUTING.HTTP_ASYNC_ACCEPT_DEFAULT Boolean Returns asynchronous acceptance by default for eligible HTTP inference requests. false No
MODELS.ROUTING.ACCEPTANCE_DB_BUSY_TIMEOUT_SEC Integer Task acceptance waits this many seconds for a busy durable-queue database. 30 No
MODELS.ROUTING.INFERENCE_TASK_RETENTION_DAYS Integer Days terminal inference task records remain in durable storage. 180 No
MODELS.ROUTING.OWNER_RUNNING_LIMITS.DEFAULT Integer Default maximum running inference tasks for one owner. 4 No
MODELS.ROUTING.OWNER_RUNNING_LIMITS.PER_OWNER_TYPE Object Object keyed by task owner type; each value sets its active-task limit and must be zero or greater. {} No
MODELS.ROUTING.DEDUPLICATION_ENABLED Boolean Coalesces eligible identical inference requests according to the configured deduplication keys. true No
MODELS.ROUTING.PROMPT_QUEUING Boolean Allows requests for a busy model to wait instead of failing immediately. false No
MODELS.ROUTING.FAIR_TASK_ROTATION Boolean Rotates scheduled work across task owners to reduce queue monopolization. false No
MODELS.ROUTING.DEDUPLICATION_KEYS List Request fields used to decide whether inference tasks are equivalent for deduplication. [] No
MODELS.ROUTING.FAILOVERS List Failover rules that select alternate models or plugins after a routing failure. [] No
MODELS.ROUTING.VIRTUAL_MODELS List Virtual model definitions that group concrete models for load balancing and failover. [] No
MODELS.ROUTING.HTTP_CLIENT_TRUST_ENV Boolean Allows model-backend HTTP clients to use proxy and certificate settings from environment variables. false Yes
MODELS.ROUTING.HTTP_CLIENT_LIMITS.MAX_CONNECTIONS Integer The HTTP client opens up to this many simultaneous connections to model backends. 200 Yes
MODELS.ROUTING.HTTP_CLIENT_LIMITS.MAX_KEEPALIVE_CONNECTIONS Integer The HTTP client keeps up to this many idle model-backend connections open. 50 Yes
MODELS.ROUTING.HTTP_CLIENT_TIMEOUTS.CONNECT Number The HTTP client stops trying to connect to a model backend after this many seconds. 30.0 Yes
MODELS.ROUTING.HTTP_CLIENT_TIMEOUTS.READ Number The HTTP client stops if a model-backend response pauses for this many seconds between reads. 300.0 Yes
MODELS.ROUTING.HTTP_CLIENT_TIMEOUTS.WRITE Number The HTTP client must send a model-backend request within this many seconds. 60.0 Yes
MODELS.ROUTING.HTTP_CLIENT_TIMEOUTS.POOL Number A request waits this many seconds for an available model-backend connection slot. 30.0 Yes
MODELS.ROUTING.HEALTH_CHECKS.INTERVAL_SEC Integer Base interval, in seconds, between model plugin health-check planning passes. 20 No
MODELS.ROUTING.HEALTH_CHECKS.JITTER_FRACTION Number Random fraction added to health-check intervals to avoid synchronized checks. 0.1 No
MODELS.ROUTING.HEALTH_CHECKS.STREAMING_IDLE_TIMEOUT_SEC Number A streaming inference attempt fails after this many seconds without a new chunk. 300.0 No
MODELS.ROUTING.HEALTH_CHECKS.NON_STREAMING_TIMEOUT_SEC Number A non-streaming inference attempt must finish within this many seconds. 300.0 No
MODELS.ROUTING.HEALTH_CHECKS.STREAMING_PREFILL_MIN_TOKENS_PER_SEC Number Assumed minimum prefill rate, in tokens per second, used to calculate a finite initial-output deadline for a long prompt. Lower values allow more time; an explicit shorter request limit still applies. 8.0 No
MODELS.ROUTING.HEALTH_CHECKS.STREAMING_PREFILL_OVERHEAD_SEC Number Fixed seconds added to the calculated prefill time when deriving the first-chunk deadline. 60.0 No
MODELS.ROUTING.HEALTH_CHECKS.PING_TIMEOUT_SEC Integer A lightweight plugin health ping must finish within this many seconds. 15 No
MODELS.ROUTING.HEALTH_CHECKS.STUCK_STATE_TIMEOUT_SEC Integer Recovery begins when a plugin remains in a transitional state for this many seconds. 900 No
MODELS.ROUTING.HEALTH_CHECKS.FLAPPING_WINDOW_SEC Integer Rolling seconds used to detect repeated plugin health-state changes. 120 No
MODELS.ROUTING.HEALTH_CHECKS.FLAPPING_MIN_TRANSITIONS Integer State transitions within the flapping window required to classify a plugin as unstable. 3 No
MODELS.ROUTING.HEALTH_CHECKS.IDLE_PING_GRACE_PERIOD_SEC Integer SoAI waits this many seconds before pinging a plugin that has just become idle. 5 No
MODELS.ROUTING.HEALTH_CHECKS.PENDING_STARTUP_TASK_TIMEOUT_SEC Integer Recovery begins when a plugin startup task remains pending for this many seconds. 300 No
MODELS.ROUTING.HEALTH_CHECKS.FAILURE_THRESHOLD Integer Consecutive qualifying health failures required before opening the plugin circuit breaker. 3 No
MODELS.ROUTING.HEALTH_CHECKS.RECOVERY_TIMEOUT_SEC Integer A plugin recovery attempt must finish within this many seconds. 1440 No
MODELS.ROUTING.HEALTH_CHECKS.FAILURE_WINDOW_SEC Integer Rolling seconds in which plugin health failures count toward recovery policy. 1440 No
MODELS.ROUTING.HEALTH_CHECKS.MAX_RECOVERY_ATTEMPTS Integer Recovery attempts allowed within the failure window before quarantine. 3 No
MODELS.ROUTING.HEALTH_CHECKS.NUM_PLANNER_WORKERS Integer Planner workers that take queued tasks from the priority queue and turn them into scheduling decisions. 16 No
MODELS.ROUTING.HEALTH_CHECKS.FAIR_DISPATCH_ENABLED Boolean Stops a plugin that has reached its share from receiving further dispatches while other plugins wait for capacity. true No
MODELS.ROUTING.HEALTH_CHECKS.FAIR_DISPATCH_MAX_PER_PLUGIN Integer Highest number of tasks one plugin may hold outstanding while fair dispatch is throttling, capped further by that plugin's own task limit. 32 No
MODELS.ROUTING.HEALTH_CHECKS.PLUGIN_QUEUE_BURST_FACTOR Integer Multiplier that expands a plugin health queue during short bursts. 4 No
MODELS.ROUTING.HEALTH_CHECKS.PLUGIN_QUEUE_MIN_SIZE Integer Minimum capacity assigned to each plugin health-check queue. 16 No
MODELS.ROUTING.HEALTH_CHECKS.PLUGIN_QUEUE_UNLIMITED_WORKERS Integer Worker count used for plugins without an explicit task-concurrency limit. 8 No
MODELS.ROUTING.HEALTH_CHECKS.PLUGIN_QUEUE_MAX_WORKERS Integer One plugin health-check queue receives up to this many workers. 32 No
MODELS.ROUTING.HEALTH_CHECKS.VIRTUAL_MODEL_FAILOVER_COOLDOWN_SEC Integer The router avoids a failed virtual-model target for this many seconds before selecting it again. 15 No
MODELS.ROUTING.HEALTH_CHECKS.MAX_CONCURRENT_TASKS_PER_PLUGIN.DEFAULT Integer Default maximum inference tasks allowed to run concurrently on one plugin. 4 No
MODELS.ROUTING.HEALTH_CHECKS.MAX_CONCURRENT_TASKS_PER_PLUGIN.PER_PLUGIN Object Object keyed by plugin name; each value sets its task concurrency limit and must be zero or greater. {} No
MODELS.ROUTING.HEALTH_CHECKS.COMMAND_TIMEOUTS_SEC.PLUGIN_STOP Integer A health-driven plugin stop command must finish within this many seconds. 300 No
MODELS.ROUTING.HEALTH_CHECKS.COMMAND_TIMEOUTS_SEC.PLUGIN_LOAD_MODEL Integer A health-driven model load command must finish within this many seconds. 7200 No
MODELS.MANAGER.PATHS.MODELS String Managed model directory, resolved under the system data directory. "models" Yes
MODELS.MANAGER.PARAMETERS.UPDATE_WORKERS Integer Workers that persist model parameter updates from the manager queue. 4 Yes
MODELS.MANAGER.PARAMETERS.UPDATE_QUEUE_MAX_SIZE Integer The manager queue holds up to this many pending model parameter updates. 20000 Yes
MODELS.MANAGER.PERFORMANCE.STARTUP_DISCOVERY_TIMEOUT_SEC Integer Initial model discovery must finish within this many seconds during startup. 3600 Yes
MODELS.MANAGER.PERFORMANCE.BACKGROUND_REFRESH_INTERVAL_MS Integer Interval, in milliseconds, between background model metadata refreshes. 60000 Yes
MODELS.MANAGER.CACHE.PARAMETER_MAX_SIZE Integer The parameter cache keeps up to this many model parameter records. 2000 Yes
MODELS.MANAGER.CACHE.RESOLUTION_TTL_SEC Integer SoAI caches a resolved model lookup for this many seconds. 300 Yes
MODELS.MANAGER.CACHE.RESOLUTION_MAX_SIZE Integer The resolution cache keeps up to this many model lookups. 5000 Yes

PLUGINS

Setting Type Description Factory default Requires restart
PLUGINS.PATHS.PLUGINS String Installed .soaiplugin directory, resolved under the SoAI installation directory. "plugins" Yes
PLUGINS.PATHS.BACKENDS String Plugin-managed backend directory, resolved under the system data directory. "backends" Yes
PLUGINS.PATHS.VENVS_ROOT String Plugin environment directory, resolved under the system data directory. "plugins/venvs" Yes
PLUGINS.PATHS.PLUGIN_LOGS String Plugin process log directory, resolved under the system data directory. "logs/plugins" Yes
PLUGINS.PATHS.TEMPLATES String Plugin and backend template directory, resolved under the system data directory. "templates" Yes
PLUGINS.FEATURES.UPLOADS Boolean Allows administrators to install plugins from uploaded .soaiplugin files. true Yes
PLUGINS.FEATURES.DOWNLOADS Boolean Allows administrators to install plugins fetched from a remote URL. true Yes
PLUGINS.BACKEND_UPDATES.AUTO_UPDATE_BUILTIN Boolean Automatically updates eligible built-in backends after a confirmed update check, once per plugin package. Enabled by default; waits for a stopped backend without active work. Third-party backends and failed automatic attempts require manual updates. true Yes
PLUGINS.SECURITY.ALLOW_INSECURE_DOWNLOADS Boolean Permits plugin downloads over unencrypted HTTP. Keep disabled outside trusted networks. false Yes
PLUGINS.SECURITY.SAFETY_VALIDATION Boolean Runs package safety checks before an uploaded or downloaded plugin is installed. true Yes
PLUGINS.PERFORMANCE.STARTUP_CONCURRENCY Integer Startup runs up to this many plugin reconciliation operations at the same time. 10 Yes
PLUGINS.PERFORMANCE.BACKEND_DRIFT_SCAN_COOLDOWN_SEC Number Minimum seconds between scans for plugin backend state that changed outside SoAI. 5.0 Yes
PLUGINS.AUTHORITATIVE_STATE.OUTBOX.SHUTDOWN_DRAIN_TIMEOUT_SEC Number Shutdown gives pending authoritative plugin-state events this many seconds to flush. 18.0 Yes
PLUGINS.RECOVERY.STARTUP_STOP_TIMEOUT_SEC Number Startup recovery gives a stale plugin process this many seconds to stop. 30.0 Yes
PLUGINS.STOP_START_TASK_CANCEL_TIMEOUT_SEC Number A conflicting plugin stop or start task gets this many seconds to cancel. 10.0 Yes

TOOLS

Setting Type Description Factory default Requires restart
TOOLS.MCP.ENABLED Boolean Starts SoAI's MCP runtime and registered tool system. Disabling it makes all MCP-backed tools unavailable. true Yes
TOOLS.MCP.OAUTH.STATE_TOKEN_TTL_MS Integer Lifetime, in milliseconds, of the signed state token used to validate an MCP OAuth callback. 600000 Yes
TOOLS.MCP.OAUTH.REFRESH_SKEW_MS Integer Milliseconds before OAuth token expiry when SoAI begins refreshing the token. 60000 Yes
TOOLS.MCP.ELICITATION.WAIT_TIMEOUT_MS Integer An MCP request waits this many milliseconds for a user's elicitation response. 3600000 Yes
TOOLS.MCP.SUBAGENT.OBSERVE_TIMEOUT_MS Integer Default milliseconds that terminal-mode subagent observation waits for a terminal state before returning the latest snapshot. Zero waits indefinitely. 0 Yes
TOOLS.MCP.SECRET_PROMPT.HANDLE_STORE_MAX_TOTAL Integer The secret-prompt store keeps up to this many unresolved handles across all users. 5000 Yes
TOOLS.MCP.SECRET_PROMPT.HANDLE_STORE_MAX_PER_USER Integer The secret-prompt store keeps up to this many unresolved handles for one user. 200 Yes
TOOLS.MCP.SHELL.ENABLED Boolean Makes the shell execution, output, search, and standard-input tools available. true Yes
TOOLS.MCP.SHELL.COMMAND_BLACKLIST List Executable names the MCP shell tools refuse to launch. [] Yes
TOOLS.MCP.FILE_GUARD_READ_BEFORE_WRITE.ENABLED Boolean Requires a tool session to read an existing file before replacing its contents. true Yes
TOOLS.MCP.BROWSER.ENABLED Boolean Makes the browser navigation, interaction, inspection, and capture tools available. true Yes
TOOLS.MCP.BROWSER.HEADLESS Boolean Runs managed browser sessions without a visible browser window. true Yes
TOOLS.MCP.BROWSER.AUTO_INSTALL Boolean Downloads the managed Playwright browser runtime when it is missing. true Yes
TOOLS.MCP.BROWSER.AUTO_INSTALL_TIMEOUT_SEC Integer Automatic browser runtime installation must finish within this many seconds. 7200 Yes
TOOLS.MCP.BROWSER.SESSION_SCOPE String Browser session sharing boundary. Accepted values are conversation and user. "conversation" Yes
TOOLS.MCP.BROWSER.DEFAULT_PROFILE String Named browser profile selected when a browser tool call does not request one. "default" Yes
TOOLS.MCP.BROWSER.PROFILES Object Object keyed by profile name; profiles may set CDP URL, persistence, browser channel, locale, time zone, viewport, scale, and launch mode. {} Yes
TOOLS.MCP.BROWSER.CDP_CONNECT_TIMEOUT_MS Integer A Chrome DevTools Protocol browser connection must open within this many milliseconds. 30000 Yes
TOOLS.MCP.BROWSER.JS_EVAL_ENABLED Boolean Makes browser_eval available for running JavaScript in the active page. true Yes
TOOLS.MCP.BROWSER.JS_EVAL_MAX_SCRIPT_CHARS Integer browser_eval rejects JavaScript source longer than this many characters. 10000 Yes
TOOLS.MCP.BROWSER.JS_EVAL_TIMEOUT_MS Integer One browser_eval script must finish within this many milliseconds. 15000 Yes
TOOLS.MCP.BROWSER.DEFAULT_NAV_TIMEOUT_SEC Integer Default navigation deadline, in seconds, for browser page loads. 30 Yes
TOOLS.MCP.BROWSER.DEFAULT_ACTION_TIMEOUT_SEC Integer Default deadline, in seconds, for browser clicks, typing, and other page actions. 15 Yes
TOOLS.MCP.BROWSER.TITLE_RETRY_ATTEMPTS Integer Attempts made to read a page title after navigation while the document settles. 3 Yes
TOOLS.MCP.BROWSER.TITLE_RETRY_DELAY_MS Integer Milliseconds between page-title read attempts. 100 Yes
TOOLS.MCP.BROWSER.MAX_WAIT_SEC Number browser_wait_for accepts an explicit wait of at most this many seconds. 300.0 Yes
TOOLS.MCP.BROWSER.RENDER_STABILIZE_MS Integer Milliseconds allowed for page rendering to settle before SoAI captures derived page state. 250 Yes
TOOLS.MCP.BROWSER.MAX_CONCURRENT_PAGES Integer The browser runtime keeps up to this many managed pages active at the same time. 10 Yes
TOOLS.MCP.BROWSER.BLOCK_IMAGES Boolean Blocks image network requests in managed browser pages. false Yes
TOOLS.MCP.BROWSER.BLOCK_FONTS Boolean Blocks web-font network requests in managed browser pages. true Yes
TOOLS.MCP.BROWSER.BLOCK_MEDIA Boolean Blocks audio and video network requests in managed browser pages. true Yes
TOOLS.MCP.BROWSER.BLOCK_ADS Boolean Blocks network requests matched by the configured advertising filter list. true Yes
TOOLS.MCP.BROWSER.AD_BLOCK_LIST_URL String URL of the filter list downloaded for browser ad blocking. "https://easylist.to/easylist/easylist.txt" Yes
TOOLS.MCP.BROWSER.DNS_TIMEOUT_SEC Number A browser navigation fails if its safety check cannot resolve the host within this many seconds. 5.0 Yes
TOOLS.MCP.BROWSER.SNAPSHOT_MAX_CHARS Integer One accessibility or DOM browser snapshot contains up to this many characters. 20000 Yes
TOOLS.MCP.BROWSER.LOG_MAX_ENTRIES Integer Maximum retained console messages, network requests, and download records for each browser session; older records are discarded. 500 Yes
TOOLS.MCP.BROWSER.STORAGE_STATE_ENABLED Boolean Persists browser cookies and origin storage between managed browser sessions. true Yes
TOOLS.MCP.BROWSER.STORAGE_STATE_DIR String Browser storage-state directory, resolved under the system data directory. "browser-storage-state" Yes
TOOLS.MCP.BROWSER.STORAGE_STATE_AUTOSAVE_ON_MUTATION Boolean Saves browser storage state after page actions that may change cookies or origin storage. true Yes
TOOLS.MCP.BROWSER.STORAGE_STATE_SAVE_THROTTLE_SEC Number Minimum seconds between automatic saves of the same browser storage state. 5.0 Yes
TOOLS.MCP.BROWSER.STORAGE_STATE_SAVE_TIMEOUT_SEC Integer Writing one browser storage-state snapshot must finish within this many seconds. 10 Yes
TOOLS.MCP.BROWSER.USER_DATA_DIR_BASE_DIR String Persistent browser profile directory, resolved under the system data directory. "browser-user-data" Yes
TOOLS.MCP.BROWSER.USER_DATA_DIR_LOCK_TIMEOUT_SEC Integer A browser session waits this many seconds to lock a persistent user-data directory. 30 Yes
TOOLS.MCP.BROWSER.PDF_MAX_INLINE_BYTES Integer browser_pdf stores a PDF as a file instead of returning it inline when it exceeds this many bytes. 1000000 Yes
TOOLS.MCP.BROWSER.NETWORK_BODY_MAX_BYTES Integer One browser network log entry captures up to this many response-body bytes. 65536 Yes
TOOLS.MCP.WEB_FETCH.BLOCK_PRIVATE_NETWORK_EGRESS Boolean Rejects web_fetch destinations that resolve to private network addresses. true Yes
TOOLS.MCP.WEB_FETCH.DNS_TIMEOUT_SEC Number web_fetch fails if its safety check cannot resolve the destination within this many seconds. 5.0 Yes
TOOLS.MCP.WEB_FETCH.DEFAULT_MAX_CHARS Integer Default maximum text characters returned by web_fetch. 50000 Yes
TOOLS.MCP.WEB_FETCH.MAX_CHARS_LIMIT Integer A web_fetch caller may request at most this many text characters. 100000 Yes
TOOLS.MCP.HTTP_REQUEST.BLOCK_PRIVATE_NETWORK_EGRESS Boolean Rejects http_request destinations that resolve to private network addresses. true Yes
TOOLS.MCP.HTTP_REQUEST.DNS_TIMEOUT_SEC Number http_request fails if its safety check cannot resolve the destination within this many seconds. 5.0 Yes
TOOLS.MCP.GENERATE_IMAGE.ENABLED Boolean Makes generate_image available. Disabling it leaves other MCP tools running. true Yes
TOOLS.MCP.GENERATE_IMAGE.ENGINE String Image service used by generate_image. Accepted values are automatic1111, comfyui, and ai_horde. "automatic1111" Yes
TOOLS.MCP.GENERATE_IMAGE.DEFAULT_WIDTH Integer Image width, in pixels, used when a generate_image call omits width. 704 Yes
TOOLS.MCP.GENERATE_IMAGE.DEFAULT_HEIGHT Integer Image height, in pixels, used when a generate_image call omits height. 704 Yes
TOOLS.MCP.GENERATE_IMAGE.DEFAULT_STEPS Integer Diffusion sampling steps used when a generate_image call omits the step count. 20 Yes
TOOLS.MCP.GENERATE_IMAGE.DEFAULT_CFG_SCALE Number Prompt guidance scale used when a generate_image call omits CFG scale. 7.0 Yes
TOOLS.MCP.GENERATE_IMAGE.NEGATIVE_PROMPT String Fallback negative prompt used when a generate_image call omits negative_prompt. "" Yes
TOOLS.MCP.GENERATE_IMAGE.TIMEOUT_SEC Integer Overall deadline, in seconds, for one image generation request. 3600 Yes
TOOLS.MCP.GENERATE_IMAGE.POLL_INTERVAL_SEC Number SoAI waits this many seconds between status polls for an asynchronous image generation job. 1.0 Yes
TOOLS.MCP.GENERATE_IMAGE.MAX_IMAGE_BYTES Integer SoAI rejects an image-service response larger than this many bytes. 134217728 Yes
TOOLS.MCP.GENERATE_IMAGE.BLOCK_PRIVATE_NETWORK_EGRESS Boolean Rejects configured image-service destinations on private networks, while allowing loopback URLs and HTTP endpoints that resolve locally. true Yes
TOOLS.MCP.GENERATE_IMAGE.DNS_TIMEOUT_SEC Number Image generation fails if its safety check cannot resolve the service host within this many seconds. 5.0 Yes
TOOLS.MCP.GENERATE_IMAGE.AUTOMATIC1111.BASE_URL String Base URL of the Automatic1111 Stable Diffusion WebUI API. "http://127.0.0.1:7860" Yes
TOOLS.MCP.GENERATE_IMAGE.AUTOMATIC1111.BASIC_AUTH String HTTP Basic authorization value sent to Automatic1111. Empty sends no Basic credentials. "" Yes
TOOLS.MCP.GENERATE_IMAGE.AUTOMATIC1111.SAMPLER_NAME String Automatic1111 sampler override. Empty lets the service use its configured default. "" Yes
TOOLS.MCP.GENERATE_IMAGE.AUTOMATIC1111.SCHEDULER String Automatic1111 scheduler override. Empty lets the service use its configured default. "" Yes
TOOLS.MCP.GENERATE_IMAGE.AUTOMATIC1111.EXTRA_PARAMS_JSON String JSON object merged into each Automatic1111 text-to-image request. "{}" Yes
TOOLS.MCP.GENERATE_IMAGE.COMFYUI.BASE_URL String Base URL of the ComfyUI API. "http://127.0.0.1:8188" Yes
TOOLS.MCP.GENERATE_IMAGE.COMFYUI.API_KEY String API key sent to ComfyUI when its endpoint requires authentication. "" Yes
TOOLS.MCP.GENERATE_IMAGE.COMFYUI.MODEL String ComfyUI checkpoint name inserted into the configured workflow. "" Yes
TOOLS.MCP.GENERATE_IMAGE.COMFYUI.WORKFLOW_JSON String ComfyUI API-format workflow submitted for image generation. "{}" Yes
TOOLS.MCP.GENERATE_IMAGE.COMFYUI.WORKFLOW_NODES List Workflow node mappings that receive prompt, model, size, seed, and sampling values. [] Yes
TOOLS.MCP.GENERATE_IMAGE.COMFYUI.OUTPUT_NODE_IDS List ComfyUI node IDs whose generated images are collected as tool output. [] Yes
TOOLS.MCP.GENERATE_IMAGE.AI_HORDE.BASE_URL String Base URL of the AI Horde generation API. "https://stablehorde.net" Yes
TOOLS.MCP.GENERATE_IMAGE.AI_HORDE.API_KEY String AI Horde API key used to submit generation jobs. "" Yes
TOOLS.MCP.GENERATE_IMAGE.AI_HORDE.MODEL String AI Horde model sent with every generate_image request that uses the AI Horde engine. "stable_diffusion" Yes
TOOLS.MCP.GENERATE_IMAGE.AI_HORDE.MAX_GENERATION_WAIT_SEC Integer SoAI stops waiting for an AI Horde job after this many seconds. 3600 Yes
TOOLS.MCP.WEATHER.ENABLED Boolean Makes the weather tool available. Disabling it leaves other MCP tools running. true Yes
TOOLS.MCP.WEATHER.GEOCODING_BASE_URL String Base URL of the location search service used by the weather tool. "https://geocoding-api.open-meteo.com" Yes
TOOLS.MCP.WEATHER.FORECAST_BASE_URL String Base URL of the forecast service used by the weather tool. "https://api.open-meteo.com" Yes
TOOLS.MCP.WEATHER.TIMEOUT_SEC Integer The weather tool stops waiting for a service response after this many seconds. 20 Yes
TOOLS.MCP.WEATHER.MAX_RESPONSE_BYTES Integer The weather tool rejects a service response larger than this many bytes. 200000 Yes
TOOLS.MCP.WEATHER.BLOCK_PRIVATE_NETWORK_EGRESS Boolean Rejects weather-service destinations on private networks, while allowing loopback URLs and HTTP endpoints that resolve locally. true Yes
TOOLS.MCP.WEATHER.DNS_TIMEOUT_SEC Number The weather tool fails if its safety check cannot resolve the service host within this many seconds. 5.0 Yes
TOOLS.MCP.NEWS.ENABLED Boolean Makes the news search tool available. Disabling it leaves other MCP tools running. true Yes
TOOLS.MCP.NEWS.BASE_URL String Base URL of the GDELT document search API used by the news tool. "https://api.gdeltproject.org/api/v2/doc" Yes
TOOLS.MCP.NEWS.TIMEOUT_SEC Integer The news tool stops waiting for a service response after this many seconds. 20 Yes
TOOLS.MCP.NEWS.MAX_RESPONSE_BYTES Integer The news tool rejects a service response larger than this many bytes. 200000 Yes
TOOLS.MCP.NEWS.BLOCK_PRIVATE_NETWORK_EGRESS Boolean Rejects news service destinations that resolve to private networks. true Yes
TOOLS.MCP.NEWS.DNS_TIMEOUT_SEC Number The news tool fails if its safety check cannot resolve the service host within this many seconds. 5.0 Yes
TOOLS.MCP.READ_IMAGE.MAX_SOURCE_BYTES Integer read_image rejects a source image larger than this many bytes. 134217728 Yes
TOOLS.MCP.READ_IMAGE.MAX_ENCODED_CHARS Integer read_image returns at most this many encoded image characters after processing. 16777216 Yes
TOOLS.MCP.READ_IMAGE.MAX_PIXELS Integer read_image reduces a decoded image until it contains no more than this many pixels. 4000000 Yes
TOOLS.MCP.READ_IMAGE.JPEG_QUALITY Integer JPEG quality used when read_image must resize or convert an image. 85 Yes
TOOLS.MCP.READ_VIDEO.DEFAULT_FRAMES_PER_SECOND Number Frame sample rate used when read_video receives no explicit rate. 1.0 Yes
TOOLS.MCP.READ_VIDEO.MAX_FRAMES_PER_SECOND Number read_video samples at most this many frames per second. 1.0 Yes
TOOLS.MCP.READ_VIDEO.FRAME_PAGE_SIZE Integer One paginated read_video result returns up to this many extracted frames. 60 Yes
TOOLS.MCP.READ_VIDEO.MAX_FRAME_PIXELS Integer read_video reduces each extracted frame to no more than this many pixels. 2000000 Yes
TOOLS.MCP.READ_VIDEO.JPEG_QUALITY Integer JPEG quality used for extracted video frames. 85 Yes
TOOLS.MCP.READ_VIDEO.INCLUDE_AUDIO_DEFAULT Boolean Extracts and transcribes video audio when a read_video call omits the audio option. true Yes
TOOLS.MCP.READ_VIDEO.AUDIO_CHUNK_SECONDS Integer Each audio segment sent for transcription spans up to this many seconds. 300 Yes
TOOLS.MCP.READ_VIDEO.JOB_RETENTION_HOURS Integer Hours completed read_video jobs and their derived files remain available. 168 Yes
TOOLS.MCP.READ_VIDEO.MAX_ACTIVE_JOBS Integer read_video runs up to this many extraction jobs at the same time. 2 Yes
TOOLS.MCP.READ_VIDEO.TEMP_RESERVATION_SAFETY_MULTIPLIER Integer Multiplier applied when reserving temporary disk space for video extraction outputs. 2 Yes
TOOLS.MCP.READ_VIDEO.VIDEO_PREVIEW_SECONDS Integer Duration, in seconds, of the lightweight video preview clip. 8 Yes
TOOLS.MCP.READ_VIDEO.VIDEO_PREVIEW_MAX_PIXELS Integer Preview generation reduces each video frame to no more than this many pixels. 307200 Yes
TOOLS.MCP.READ_VIDEO.VIDEO_PREVIEW_CRF Integer Constant Rate Factor used to control preview-video compression quality and size. 28 Yes
TOOLS.MCP.READ_VIDEO.VIDEO_PREVIEW_MAX_BYTES Integer read_video keeps a generated preview only when it is no larger than this many bytes. 8388608 Yes
TOOLS.MCP.READ_VIDEO.PROBE_TIMEOUT_SEC Integer The media probe must inspect a video's metadata within this many seconds. 60 Yes
TOOLS.MCP.READ_VIDEO.FRAME_EXTRACTION_TIMEOUT_SEC Integer Requested video frames must finish extracting within this many seconds. 900 Yes
TOOLS.MCP.READ_VIDEO.AUDIO_EXTRACTION_TIMEOUT_SEC Integer Video audio extraction and preparation must finish within this many seconds. 900 Yes
TOOLS.MCP.READ_VIDEO.PREVIEW_EXTRACTION_TIMEOUT_SEC Integer A lightweight video preview must finish within this many seconds. 300 Yes
TOOLS.MCP.READ_VIDEO.LIVE_PROGRESS_MIN_INTERVAL_MS Integer Minimum milliseconds between live progress updates from a read_video job. 1000 Yes
TOOLS.MCP.READ_VIDEO.WHISPER_MODEL String Speech-to-text model for media transcripts: Auto, a Whisper size, or a concrete local model reference. Existing saved selections are preserved. "auto" Yes
TOOLS.MCP.HOST_MODE.ENABLED Boolean Allows SoAI to act as an MCP client and connect to external MCP servers. true Yes
TOOLS.MCP.HOST_MODE.AUTO_CONNECT_ON_STARTUP Boolean Reconnects saved external MCP servers when the MCP runtime starts. true Yes
TOOLS.MCP.HOST_MODE.RECONNECT_DELAY_SEC Integer SoAI waits this many seconds between attempts to reconnect an external MCP server. 5 Yes
TOOLS.MCP.HOST_MODE.MAX_RECONNECT_ATTEMPTS Integer Reconnect attempts made before an external MCP server remains disconnected. 3 Yes
TOOLS.MCP.HOST_MODE.ROOTS List Filesystem roots SoAI advertises to connected MCP servers. [] Yes
TOOLS.MCP.HOST_MODE.ROOTS_LIST_CHANGED Boolean Sends roots/list_changed notifications when the advertised root list changes. true Yes
TOOLS.MCP.HOST_MODE.SAMPLING.ENABLED Boolean Allows connected MCP servers to request model sampling through SoAI. false Yes
TOOLS.MCP.HOST_MODE.SAMPLING.DEFAULT_MODEL String Model used for an MCP sampling request that does not specify one. "" Yes
TOOLS.MCP.HOST_MODE.SAMPLING.INFERENCE_TIMEOUT_SEC Integer A server-requested model sampling call must finish within this many seconds. 300 Yes
TOOLS.MCP.HOST_MODE.ELICITATION.ENABLED Boolean Allows connected MCP servers to request structured input from the user. false Yes
TOOLS.MCP.SERVER_MODE.ENABLED Boolean Exposes SoAI's selected tools, resources, and prompts through its MCP HTTP server. true Yes
TOOLS.MCP.SERVER_MODE.EXPOSED_TOOLS List Registered SoAI tool names visible to MCP server-mode clients. ["web_fetch", "web_search_duckduckgo", "web_search_searxng", "web_search_brave", "web_search_tavily", "web_search_serper", "web_search_google", "calculator", "rss_read", "news", "weather", "datetime_current", "hardware_snapshot", "wait", "random_generate", "hash", "base64", "text_stats", "unit_convert"] Yes
TOOLS.MCP.SERVER_MODE.EXPOSED_RESOURCES List Registered SoAI resource names visible to MCP server-mode clients. ["models", "plugins", "system_status"] Yes
TOOLS.MCP.SERVER_MODE.EXPOSED_PROMPTS List Registered SoAI prompt names visible to MCP server-mode clients. ["system_overview", "model_selection", "plugin_info", "rag_document_summary", "rag_topic_extraction", "rag_question_answering", "rag_compare_sources"] Yes
TOOLS.MCP.SERVER_MODE.ALLOWED_ORIGINS List Browser origins allowed to call the MCP HTTP endpoint. Empty applies the server default. [] Yes
TOOLS.MCP.SERVER_MODE.LIST_CHANGED_NOTIFICATIONS Boolean Notifies connected clients when exposed tool, resource, or prompt lists change. false Yes
TOOLS.MCP.SERVER_MODE.SSE_REPLAY_BUFFER_SIZE Integer The MCP stream replay buffer keeps up to this many server notifications for reconnecting clients. 256 Yes
TOOLS.MCP.TASKS.ENABLED Boolean Enables the MCP Tasks protocol for asynchronous tool execution. false Yes
TOOLS.MCP.TASKS.DEFAULT_TTL_SEC Integer Default seconds an MCP task remains available after creation. 3600 Yes
TOOLS.MCP.TASKS.MAX_CONCURRENT_PER_CLIENT Integer One connected client may run up to this many MCP tasks at the same time. 100 Yes
TOOLS.MCP.TASKS.PROXY_TIMEOUT_SEC Integer SoAI stops proxying an unfinished MCP task after this many seconds. 3600 Yes
TOOLS.MCP.TASKS.TOOL_TIMEOUT_SEC Number Tool execution owned by an MCP task must finish within this many seconds. 600.0 Yes
TOOLS.MCP.CLIENT_NOTIFICATION_QUEUE_SIZE Integer One MCP client session buffers up to this many pending server notifications. 1024 Yes
TOOLS.MCP.SESSION_TTL_SEC Integer SoAI expires an inactive MCP server-mode session after this many seconds. 3600 Yes
TOOLS.MCP.SESSION_SWEEP_INTERVAL_SEC Integer Interval, in seconds, between removal passes for expired MCP sessions. 300 Yes
TOOLS.MEDIA_PARSING.VIDEO_OCR_FRAMES_PER_SECOND Number Video frame sample rate used when extracting visible text with OCR. 1.0 Yes
TOOLS.MEDIA_PARSING.VIDEO_OCR_MAX_FRAMES Integer OCR inspects up to this many sampled video frames during one parse. 360 Yes
TOOLS.MEDIA_PARSING.VIDEO_OCR_MAX_TEXT_CHARS Integer One parsed video contributes up to this many OCR characters. 250000 Yes
TOOLS.MEDIA_PARSING.OCR_FRAME_TIMEOUT_SEC Integer OCR on one sampled video frame must finish within this many seconds. 60 Yes
TOOLS.MEDIA_PARSING.PARSE_TIMEOUT_SEC Integer Overall deadline, in seconds, for one document, audio, image, or video parse job. 21600 Yes
TOOLS.RAG.ENABLED Boolean Starts the knowledge-base indexing, retrieval, and configured web-search capabilities. true Yes
TOOLS.RAG.CHROMA_PATH String Chroma vector index directory, resolved under the system data directory. "chroma_rag" Yes
TOOLS.RAG.CHROMA_SHARD_COUNT Integer Number of isolated Chroma worker shards used for vector index operations. 1 Yes
TOOLS.RAG.CHROMA_IPC_STARTUP_TIMEOUT_SEC Integer Chroma worker IPC must become ready within this many seconds. 300 Yes
TOOLS.RAG.CHROMA_IPC_RETRY_COUNT Integer Additional attempts made after a Chroma IPC operation fails transiently. 1 Yes
TOOLS.RAG.CHROMA_IPC_JOB_TTL_SEC Integer A submitted Chroma IPC job remains recoverable for this many seconds before it expires. 3600 Yes
TOOLS.RAG.CHROMA_QUERY_TIMEOUT_SEC Integer A Chroma vector similarity query must finish within this many seconds. 30 Yes
TOOLS.RAG.CHROMA_DELETE_TIMEOUT_SEC Integer A Chroma vector deletion must finish within this many seconds. 30 Yes
TOOLS.RAG.CHROMA_ADD_TIMEOUT_SEC Integer A Chroma vector insertion batch must finish within this many seconds. 600 Yes
TOOLS.RAG.CHROMA_ADD_CANCEL_WAIT_SEC Integer SoAI waits this many seconds for a cancelled Chroma insertion to stop. 2 Yes
TOOLS.RAG.REINDEX_CHUNK_PAGE_SIZE Integer Document chunks processed per page while rebuilding a knowledge index. 256 Yes
TOOLS.RAG.DEFAULT_EMBEDDING_MODEL String Embedding model used for knowledge collections that do not select one. Auto resolves an available model. "auto" Yes
TOOLS.RAG.PROCESSING_WORKERS Integer Workers that parse, chunk, embed, and index queued knowledge documents. 3 Yes
TOOLS.RAG.PROCESSING_QUEUE_SIZE Integer The in-memory knowledge processing queue holds up to this many waiting jobs. 1024 Yes
TOOLS.RAG.PROCESSING_JOB_LEASE_TTL_SEC Integer Recovery may claim a knowledge processing job after its lease has gone unrenewed for this many seconds. 900 Yes
TOOLS.RAG.EMBEDDING_TIMEOUT Integer An embedding request must finish within this many seconds. 300 Yes
TOOLS.RAG.EMBEDDING_RETRY_ATTEMPTS Integer SoAI makes this many attempts for an embedding batch that fails transiently. 6 Yes
TOOLS.RAG.EMBEDDING_BATCH_SIZE Integer One embedding request contains up to this many text chunks. 64 Yes
TOOLS.RAG.EMBEDDING_MAX_BATCH_CHARS Integer One embedding request contains up to this many combined source characters. 24000 Yes
TOOLS.RAG.CHROMA_ADD_BATCH_SIZE Integer One Chroma insertion batch writes up to this many vector records. 64 Yes
TOOLS.RAG.SPARSE_INDEX_DIR String Lexical sparse index directory, resolved under the system data directory. "rag_sparse_index" Yes
TOOLS.RAG.DEFAULT_CHUNK_SIZE Integer Default target size of indexed text chunks, counted in tokens by the token based strategy and in characters by the others. 500 Yes
TOOLS.RAG.DEFAULT_CHUNK_OVERLAP Integer Default overlap repeated between adjacent indexed chunks, in the unit its chunking strategy counts; paragraph ignores it and semantic converts it to whole sentences. 100 Yes
TOOLS.RAG.DEFAULT_TOP_K Integer Default number of highest-scoring knowledge passages returned by a search. 5 Yes
TOOLS.RAG.DEFAULT_SIMILARITY_THRESHOLD Number Default minimum vector similarity score required for a knowledge result. 0.3 Yes
TOOLS.RAG.BRAVE.DEFAULT_SEARCH_LANG String Brave Search language code used when a web search omits language. "en" Yes
TOOLS.RAG.BRAVE.DEFAULT_COUNTRY String Brave Search country code used when a web search omits country. "US" Yes
TOOLS.RAG.DUCKDUCKGO.BACKEND String DuckDuckGo search implementation to use. Auto selects the supported backend. "auto" Yes
TOOLS.RAG.DUCKDUCKGO.PROXY String Proxy URL passed to DuckDuckGo search requests. Empty connects without a DuckDuckGo proxy and does not use the shared web proxy settings. "" Yes
TOOLS.RAG.DUCKDUCKGO.TIMEOUT Integer A DuckDuckGo search request must finish within this many seconds. 10 Yes
TOOLS.RAG.GOOGLE.DEFAULT_SAFE String Google Programmable Search safe-search mode used when a call omits it. "active" Yes
TOOLS.RAG.GOOGLE.SEARCH_ENGINE_ID String Google Programmable Search engine identifier paired with the configured Google API credential. "" Yes
TOOLS.RAG.SEARXNG.BASE_URL String Base URL of the SearXNG instance used for web search. "" Yes
TOOLS.RAG.SEARXNG.DEFAULT_CATEGORIES List SearXNG categories requested when a search does not specify categories. ["general"] Yes
TOOLS.RAG.SEARXNG.ENGINES List SearXNG engines explicitly requested for each search. Empty lets the instance choose. [] Yes
TOOLS.RAG.SERPER.DEFAULT_GL String Serper geographic country code used when a search omits gl. "us" Yes
TOOLS.RAG.SERPER.DEFAULT_HL String Serper interface language code used when a search omits hl. "en" Yes
TOOLS.RAG.TAVILY.DEFAULT_SEARCH_DEPTH String Tavily search-depth mode used when a search omits it. "basic" Yes
TOOLS.RAG.TAVILY.INCLUDE_ANSWER Boolean Requests Tavily's generated answer in addition to the source search results. false Yes
TOOLS.RAG.WEB.ENABLED Boolean Makes configured web search and knowledge web-fetch tools available. true Yes
TOOLS.RAG.WEB.DEFAULT_PROVIDER String Search provider used when a web-search tool call does not name one. "duckduckgo" Yes
TOOLS.RAG.WEB.MAX_URL_SIZE_MB Integer Knowledge web fetching rejects a remote document larger than this many megabytes. 10 Yes
TOOLS.RAG.WEB.REQUEST_TIMEOUT Integer Default HTTP request deadline, in seconds, for search provider calls. 30 Yes
TOOLS.RAG.WEB.FETCH_TOTAL_TIMEOUT_SEC Integer Overall deadline, in seconds, for a standard document fetch and parse. 30 Yes
TOOLS.RAG.WEB.FETCH_VARIANTS_TOTAL_TIMEOUT_SEC Integer Overall deadline, in seconds, when a fetch tries alternate retrieval variants. 35 Yes
TOOLS.RAG.WEB.DNS_TIMEOUT_SEC Integer A web search or fetch fails if its safety check cannot resolve the destination within this many seconds. 5 Yes
TOOLS.RAG.WEB.STREAM_CHUNK_SIZE Integer Bytes read per streamed response chunk while fetching a remote document. 65536 Yes
TOOLS.RAG.WEB.HTML_PARSE_TIMEOUT Integer Readable-content extraction from fetched HTML must finish within this many seconds. 60 Yes
TOOLS.RAG.WEB.PDF_PARSE_TIMEOUT Integer Text extraction from a fetched PDF must finish within this many seconds. 300 Yes
TOOLS.RAG.WEB.CONTENT_MAX_CHARS Integer SoAI keeps up to this many extracted characters from one fetched document. 120000 Yes
TOOLS.RAG.WEB.CONTENT_TRIM_MODE String Method used at the fetched-text limit. sentence trims at a text boundary; hard cuts at the exact character count. "sentence" Yes
TOOLS.RAG.WEB.USER_AGENT String Default HTTP User-Agent header sent when fetching web documents. "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36" Yes
TOOLS.RAG.WEB.ACCEPT_LANGUAGE String HTTP Accept-Language header sent when fetching web documents. "en-US,en;q=0.9" Yes
TOOLS.RAG.WEB.ACCEPT_HEADER String HTTP Accept header sent when fetching web documents. "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8" Yes
TOOLS.RAG.WEB.FETCH_RETRY_ATTEMPTS Integer Total number of web-fetch attempts for an eligible transient failure, including the first request. 3 Yes
TOOLS.RAG.WEB.FETCH_RETRY_DELAY Integer Base delay, in seconds, between eligible web-fetch retries. 2 Yes
TOOLS.RAG.WEB.FETCH_CONTEXT.MAX_TOP_K Integer Compact fetched context includes up to this many passages for the model. 8 Yes
TOOLS.RAG.WEB.FETCH_CONTEXT.MAX_PASSAGE_CHARS Integer Compact fetched context keeps up to this many characters from one passage. 700 Yes
TOOLS.RAG.WEB.FETCH_CONTEXT.MAX_TOTAL_CHARS Integer Compact fetched context contains up to this many combined characters. 2048 Yes
TOOLS.RAG.WEB.MARKDOWN.STRIP_IMAGES Boolean Removes image references while converting fetched pages to readable Markdown. true Yes
TOOLS.RAG.WEB.URL_CACHE.ENABLED Boolean Caches processed web documents by canonical URL. true Yes
TOOLS.RAG.WEB.URL_CACHE.TTL_SEC Integer The URL cache keeps a processed web document valid for this many seconds. 3600 Yes
TOOLS.RAG.WEB.SEARCH_RETRY_ATTEMPTS Integer Total number of search-provider attempts for an eligible transient failure, including the first request. 3 Yes
TOOLS.RAG.WEB.SEARCH_RETRY_DELAY Integer Base delay, in seconds, between eligible search-provider retries. 2 Yes
TOOLS.RAG.WEB.USER_AGENT_ROTATION.ENABLED Boolean Varies the User-Agent header across web document fetches. true Yes
TOOLS.RAG.WEB.USER_AGENT_ROTATION.MODE String User-Agent selection policy. sequential rotates in order; any other value selects randomly. "random" Yes
TOOLS.RAG.WEB.USER_AGENT_ROTATION.CUSTOM_AGENTS List Additional User-Agent strings available to the fetch rotation policy. [] Yes
TOOLS.RAG.WEB.PROXY.ENABLED Boolean Routes eligible web search and document-fetch traffic through configured proxies. false Yes
TOOLS.RAG.WEB.PROXY.HTTP_PROXY String HTTP proxy used when no rotation-list, SOCKS5, or HTTPS proxy is configured. "" Yes
TOOLS.RAG.WEB.PROXY.HTTPS_PROXY String HTTPS proxy used for eligible web requests when no rotation-list or SOCKS5 proxy is configured; it takes precedence over HTTP_PROXY. "" Yes
TOOLS.RAG.WEB.PROXY.SOCKS5_PROXY String SOCKS5 proxy URL available for supported outbound web requests. "" Yes
TOOLS.RAG.WEB.PROXY.NO_PROXY String Comma-separated hostnames that bypass configured web proxies. Matching is case-insensitive and exact; networks, suffixes, ports, and wildcards are not interpreted. "localhost,127.0.0.1" Yes
TOOLS.RAG.WEB.PROXY.ROTATION_ENABLED Boolean Chooses among configured proxy-list entries across eligible requests. false Yes
TOOLS.RAG.WEB.PROXY.PROXY_LIST List Additional proxy URLs available to the web proxy rotation policy. [] Yes
TOOLS.RAG.WEB.BROWSER_RENDER_ON_TIMEOUT_ENABLED Boolean Retries a timed-out direct web fetch with a managed browser renderer. true Yes
TOOLS.RAG.WEB.BROWSER_RENDER_ON_HTTP_ERROR_ENABLED Boolean Retries selected direct-fetch HTTP errors with a managed browser renderer. true Yes
TOOLS.RAG.WEB.BROWSER_RENDER_ON_HTTP_ERROR_STATUS_CODES List HTTP status codes that may trigger a browser-rendered fetch retry. [403, 429] Yes
TOOLS.RAG.WEB.BROWSER_RENDER_HEADLESS Boolean Runs the fallback web document renderer without a visible browser window. true Yes
TOOLS.RAG.WEB.BROWSER_RENDER_NAV_TIMEOUT_SEC Integer Fallback browser navigation must finish within this many seconds. 30 Yes
TOOLS.RAG.WEB.BROWSER_RENDER_STABILIZE_MS Integer Milliseconds the fallback renderer waits for page content to settle after navigation. 750 Yes
TOOLS.RAG.WEB.BROWSER_RENDER_MAX_CONCURRENT_PAGES Integer The fallback renderer keeps up to this many pages active at the same time. 2 Yes
TOOLS.RAG.WEB.BROWSER_RENDER_BLOCK_IMAGES Boolean Blocks image requests in fallback-renderer pages. true Yes
TOOLS.RAG.WEB.BROWSER_RENDER_BLOCK_FONTS Boolean Blocks web-font requests in fallback-renderer pages. true Yes
TOOLS.RAG.WEB.BROWSER_RENDER_BLOCK_MEDIA Boolean Blocks audio and video requests in fallback-renderer pages. true Yes
TOOLS.RAG.WEB.BROWSER_RENDER_BLOCK_ADS Boolean Blocks advertising requests in fallback-renderer pages. true Yes

DATA

Setting Type Description Factory default Requires restart
DATA.DATABASE.PATHS.SYSTEM_DB String Primary SQLite database path, resolved under the system data directory. "database/soai.db" Yes
DATA.DATABASE.SQLITE.CONNECT_TIMEOUT_SEC Integer SQLite waits this many seconds for a locked database when opening a connection. 10 Yes
DATA.DATABASE.SQLITE.VACUUM_INTERVAL_HOURS Integer Minimum hours since the last successful SQLite VACUUM before maintenance is considered at startup. Set to 0 to disable automatic VACUUM. 720 Yes
DATA.DATABASE.SQLITE.READ_POOL_MAX_SIZE Integer The connection pool keeps up to this many read-only SQLite connections. 8 Yes
DATA.DATABASE.SQLITE.READ_MMAP_SIZE_MB Integer Read connections use an SQLite memory-mapped I/O region of up to this many megabytes. 4096 Yes
DATA.DATABASE.SQLITE.WRITE_MMAP_SIZE_MB Integer The writer connection uses an SQLite memory-mapped I/O region of up to this many megabytes. 4096 Yes
DATA.DATABASE.WRITER.INIT_TIMEOUT_SEC Integer The serialized database writer must initialize within this many seconds. 120 Yes
DATA.DATABASE.WRITER.SHUTDOWN_TIMEOUT_SEC Integer The database writer gets this many seconds to stop during shutdown. 5 Yes
DATA.DATABASE.WRITER.OPERATION_TIMEOUT_SEC Integer A queued database write must finish within this many seconds. 120 Yes
DATA.DATABASE.METRICS.IO_LOGGING Boolean Records sampled database read and write timing in diagnostic logs. false Yes
DATA.DATABASE.METRICS.IO_SAMPLE_INTERVAL_SEC Integer Minimum seconds between database I/O diagnostic samples. 1 Yes
DATA.FILES.PATHS.FILES_STORAGE String Managed files directory, resolved under the system data directory. "files" Yes
DATA.FILES.RECONCILIATION_CONCURRENCY Integer SoAI reconciles up to this many file records with disk contents at the same time. 32 Yes
DATA.FILES.INITIAL_CLEANUP_ENABLED Boolean Removes stale managed-file records and abandoned temporary files during startup reconciliation. true Yes
DATA.FILES.DIRECTORY_SCAN_TIMEOUT_SEC Number A managed-files directory scan must finish within this many seconds. 600.0 Yes
DATA.FILE_EXPLORER.ENABLED Boolean Makes the managed file explorer and its file operations available. true Yes
DATA.FILE_EXPLORER.MAX_DOWNLOAD_ARCHIVE_SIZE_MB Integer The file explorer rejects a generated directory-download archive larger than this many megabytes. 4096 Yes
DATA.FILE_EXPLORER.MAX_DOWNLOAD_ARCHIVE_MEMBERS Integer One generated download archive contains up to this many files and directories. 100000 Yes
DATA.FILE_EXPLORER.TEXT_PREVIEW_LIMIT_KB Integer An inline text preview reads up to this many kilobytes from a file. 1024 Yes
DATA.FILE_EXPLORER.LISTING_PAGINATION_LIMIT Integer Default maximum entries returned in one file explorer directory page. 100 Yes
DATA.BACKUP.ENABLED Boolean Enables manual and scheduled SoAI backups. true Yes
DATA.BACKUP.BACKUPS_PATH String Managed backup directory, resolved under the system data directory. "backups" Yes
DATA.BACKUP.SQLITE_BACKUP_TIMEOUT_SECONDS Integer Base deadline, in seconds, for copying the SQLite database into a backup. 3600 Yes
DATA.BACKUP.SQLITE_BACKUP_TIMEOUT_SECONDS_PER_GIB Integer Additional database backup seconds allowed for each GiB of SQLite data. 900 Yes
DATA.BACKUP.CONFIG_LOCK_TIMEOUT_SECONDS Integer A backup waits this many seconds to lock the Core configuration files. 30 Yes
DATA.BACKUP.PLUGIN_LOCK_TIMEOUT_SECONDS Integer A backup waits this many seconds to lock plugin configuration files. 15 Yes
DATA.BACKUP.OPERATIONS_LOCK_TIMEOUT_SECONDS Integer A backup or restore waits this many seconds for the global operations lock. 300 Yes
DATA.BACKUP.EXPORT_LOCK_TIMEOUT_SECONDS Integer An archive export waits this many seconds for access to a completed backup. 5 Yes
DATA.BACKUP.RESTORE_COPY_TIMEOUT_SECONDS Integer Restored files must finish copying into their managed locations within this many seconds. 1800 Yes
DATA.BACKUP.RESTORE_PROGRESS_INTERVAL_SECONDS Number Minimum seconds between restore progress updates. 2.0 Yes
DATA.BACKUP.SCHEDULE.INTERVAL_HOURS Integer Hours between recurring scheduled backup attempts. 24 Yes
DATA.BACKUP.SCHEDULE.RUN_ON_STARTUP Boolean Queues a backup after SoAI finishes startup recovery. false Yes
DATA.BACKUP.SCHEDULE.ON_SHUTDOWN Boolean Attempts a final managed backup during clean shutdown. false Yes
DATA.BACKUP.SCHEDULE.ON_SHUTDOWN_TIMEOUT_SEC Integer A shutdown backup gets this many seconds to finish. 120 Yes
DATA.BACKUP.SCHEDULE.RETRY_BASE_SECONDS Integer Initial delay, in seconds, before retrying a failed scheduled backup. 60 Yes
DATA.BACKUP.SCHEDULE.RETRY_MAX_SECONDS Integer Repeated scheduled backup failures increase the retry delay up to this many seconds. 1800 Yes
DATA.BACKUP.RETENTION.MAX_BACKUPS Integer A retention pass keeps up to this many completed backups. 7 Yes
DATA.BACKUP.RETENTION.MAX_AGE_HOURS Integer Retention removes a completed backup after this many hours. 720 Yes
DATA.BACKUP.RETENTION.STALE_PART_THRESHOLD_HOURS Integer Age, in hours, after which an incomplete backup part is considered stale. 1 Yes
DATA.BACKUP.RETENTION.ORPHAN_AGE_HOURS Integer Age, in hours, after which untracked backup files are eligible for cleanup. 168 Yes
DATA.BACKUP.TARGETS.DATABASE Boolean Includes the primary SoAI database in managed backups. true Yes
DATA.BACKUP.TARGETS.CONFIG Boolean Includes the active and factory Core configuration files in managed backups. true Yes
DATA.BACKUP.TARGETS.ENCRYPTION_KEY Boolean Includes the system encryption key needed to read protected restored values. true Yes
DATA.BACKUP.TARGETS.PLUGIN_CONFIGS Boolean Includes installed plugin sidecar configuration files in managed backups. true Yes
DATA.BACKUP.TARGETS.USER_DATA Boolean Includes user-managed files and other backed-up user data. true Yes
DATA.BACKUP.TARGETS.GPU_SETTINGS Boolean Includes saved GPU settings slots in managed backups. true Yes
DATA.BACKUP.TARGETS.LOGS Boolean Includes application and plugin log files in managed backups. false Yes

INTEGRATIONS

Setting Type Description Factory default Requires restart
INTEGRATIONS.MAIL.SYNC.ENABLED Boolean Runs periodic synchronization for configured mail accounts. true Yes
INTEGRATIONS.MAIL.SYNC.INTERVAL_SEC Integer Mail synchronization runs at this interval in seconds. 120 Yes
INTEGRATIONS.MAIL.SYNC.HISTORY.MAX_AGE_DAYS Integer Oldest message age, in days, retained by routine mail synchronization. 30 Yes
INTEGRATIONS.MAIL.SYNC.HISTORY.MAX_MESSAGES_PER_FOLDER Integer Routine synchronization keeps up to this many messages from each folder. 5000 Yes
INTEGRATIONS.MAIL.SYNC.FOLDERS.INCLUDE_SPECIAL_USE Boolean Automatically synchronizes folders advertised by the server for standard roles such as Sent and Trash. true Yes
INTEGRATIONS.MAIL.SYNC.FOLDERS.INCLUDE_NAMES List Additional mail folder names included in routine synchronization. [] Yes
INTEGRATIONS.MAIL.SYNC.FOLDERS.EXCLUDE_NAMES List Mail folder names excluded from routine synchronization. ["Junk", "Spam"] Yes
INTEGRATIONS.MAIL.LIMITS.LIST_DEFAULT Integer Default number of messages returned by a mail list request. 50 Yes
INTEGRATIONS.MAIL.LIMITS.LIST_MAX Integer A mail list request may return at most this many messages. 200 Yes
INTEGRATIONS.MAIL.LIMITS.READ_MAX_CHARS Integer Reading one email returns up to this many message-body characters. 50000 Yes
INTEGRATIONS.MAIL.LIMITS.SNIPPET_MAX_CHARS Integer A mail message snippet stores and returns up to this many characters. 500 Yes
INTEGRATIONS.MAIL.LIMITS.ATTACHMENT_MAX_BYTES Integer Mail upload and download reject an attachment larger than this many bytes. 25000000 Yes
INTEGRATIONS.MAIL.TIMEOUTS.CONNECT_SEC Number Mail server connection and authentication must finish within this many seconds. 30.0 Yes
INTEGRATIONS.MAIL.TIMEOUTS.COMMAND_SEC Number A remote mail protocol command must finish within this many seconds. 30.0 Yes
INTEGRATIONS.MAIL.CONCURRENCY.MAX_CONCURRENT_PER_ACCOUNT Integer One account may run this many mail operations at the same time. 2 Yes
INTEGRATIONS.MAIL.BACKFILL.BATCH_LIMIT_DEFAULT Integer Default messages requested per folder history backfill batch. 200 Yes
INTEGRATIONS.MAIL.BACKFILL.BATCH_LIMIT_MAX Integer A folder history backfill batch may request at most this many messages. 1000 Yes
INTEGRATIONS.MAIL.REMOTE_SEARCH.LIMIT_DEFAULT Integer Default maximum messages returned by a server-side mail search. 50 Yes
INTEGRATIONS.MAIL.REMOTE_SEARCH.LIMIT_MAX Integer A server-side mail search may request at most this many results. 200 Yes
INTEGRATIONS.MAIL.REMOTE_SEARCH.REQUIRE_NARROWING_FILTER Boolean Rejects remote mail searches that provide no account, folder, sender, date, or text constraint. true Yes
INTEGRATIONS.MAIL.REMOTE_SEARCH.TEXT_REQUIRES_TIME_BOUND Boolean Requires a date range when a remote mail search includes free text. true Yes
INTEGRATIONS.CALENDAR.SYNC.ENABLED Boolean Runs periodic synchronization for configured calendar accounts. true Yes
INTEGRATIONS.CALENDAR.SYNC.INTERVAL_SEC Integer Calendar synchronization runs at this interval in seconds. 300 Yes
INTEGRATIONS.CALENDAR.SYNC.WINDOW.PAST_DAYS Integer Days before today included in the routine calendar synchronization window. 90 Yes
INTEGRATIONS.CALENDAR.SYNC.WINDOW.FUTURE_DAYS Integer Days after today included in the routine calendar synchronization window. 365 Yes
INTEGRATIONS.CALENDAR.SYNC.WINDOW.MAX_RANGE_DAYS Integer A requested calendar window sync may span at most this many days. 365 Yes
INTEGRATIONS.CALENDAR.LIMITS.LIST_DEFAULT Integer Default number of calendar events returned by a list request. 100 Yes
INTEGRATIONS.CALENDAR.LIMITS.LIST_MAX Integer A calendar list request may return at most this many events. 500 Yes
INTEGRATIONS.CALENDAR.RECURRENCE.MAX_EXPANSIONS_PER_EVENT Integer One query expands a recurring calendar event into up to this many instances. 500 Yes
INTEGRATIONS.CALENDAR.TIMEOUTS.REQUEST_SEC Number A remote calendar service request must finish within this many seconds. 30.0 Yes

AUTOMATION

Setting Type Description Factory default Requires restart
AUTOMATION.SCHEDULER_TICK_SECONDS Number Interval, in seconds, between checks for automation runs that are due. 10.0 Yes
AUTOMATION.DUE_BATCH_LIMIT Integer One scheduler tick claims up to this many due automation runs. 100 Yes
AUTOMATION.MAX_CONCURRENT_RUNS Integer SoAI runs up to this many automations at the same time across all users. 2 Yes
AUTOMATION.MAX_CONCURRENT_RUNS_PER_USER Integer One user may have this many automation runs active at the same time. 1 Yes
AUTOMATION.DISALLOWED_UNQUALIFIED_TOOLS List Automations may call these tool names only with a server-qualified name. [] Yes

OBSERVABILITY

Setting Type Description Factory default Requires restart
OBSERVABILITY.LOGGING.ENABLED Boolean Enables SoAI application logging. true Yes
OBSERVABILITY.LOGGING.LOGS_PATH String Application log directory, resolved under the system data directory. "logs" Yes
OBSERVABILITY.LOGGING.LOG_LEVEL String Lowest severity written to the main and console logs. "INFO" Yes
OBSERVABILITY.LOGGING.MAIN_LOG String File name of the primary SoAI application log. "soai.log" Yes
OBSERVABILITY.LOGGING.CONSOLE_COLOR Boolean Uses ANSI colors for supported console log output. true Yes
OBSERVABILITY.LOGGING.CONSOLE_LOGGING Boolean Writes application log records to the process console. true Yes
OBSERVABILITY.LOGGING.STREAMING_LOG_BUFFER_SIZE Integer The WebUI log-stream buffer keeps this many recent records. 10000 Yes
OBSERVABILITY.LOGGING.MAIN_LOG_BACKUP_COUNT Integer Number of rotated main log files retained on disk. 5 Yes
OBSERVABILITY.LOGGING.LOGGING_SYSTEM.MAIN_LOG_ENABLE_JSON_LOGGING Boolean Writes each main log record as structured JSON instead of formatted text. false Yes
OBSERVABILITY.LOGGING.LOGGING_SYSTEM.MAIN_LOG_COMPRESS_LOGS Boolean Compresses rotated main log files. false Yes
OBSERVABILITY.LOGGING.AUDIT.PATH String Path to the append-only JSON Lines audit log. "soai.audit.jsonl" Yes
OBSERVABILITY.METRICS.CONSERVATIVE_BILLING_CHAR_THRESHOLD Integer Reserved character threshold loaded into the orchestrator. Current result accounting does not apply it. 25 Yes
OBSERVABILITY.METRICS.BACKGROUND_QUEUE_MAXSIZE Integer The background persistence queue holds up to this many metric records. 100000 Yes
OBSERVABILITY.METRICS.BROADCAST_INTERVAL_MS Integer Minimum interval, in milliseconds, between live metric broadcasts to WebUI clients. 1000 Yes
OBSERVABILITY.METRICS.METRICS_HISTORY.ENABLED Boolean Stores metric samples for historical charts and queries. true Yes
OBSERVABILITY.METRICS.METRICS_HISTORY.LOGGING_INTERVAL_MS Integer Interval, in milliseconds, between persisted metric history samples. 3000 Yes
OBSERVABILITY.METRICS.METRICS_HISTORY.PRUNING_INTERVAL_SEC Integer Interval, in seconds, between metric history retention passes. 300 Yes
OBSERVABILITY.METRICS.METRICS_HISTORY.DB_RETENTION_HOURS Integer Number of hours metric history remains in the database. 168 Yes
OBSERVABILITY.METRICS.METRICS_HISTORY.MAX_POINTS Integer One metric history query accepts and returns up to this many data points. 50000 Yes
OBSERVABILITY.METRICS.METRICS_HISTORY.SUPPORTED_INTERVALS_MS List Sampling intervals, in milliseconds, accepted by metric history queries. [3000, 60000, 300000, 900000, 3600000, 21600000, 86400000] Yes
OBSERVABILITY.METRICS.METRICS_HISTORY.TRACKED_METRICS List Metric names stored in history. An empty list uses the built-in tracked set. [] Yes
OBSERVABILITY.METRICS.RESET_GENESIS_ON_CLEAR Boolean Starts a new cumulative metrics baseline when stored metric history is cleared. false Yes

Related documentation