Security hardening

SoAI is a management plane for models, accounts, files, tools, and host resources. Its security controls reduce common web, credential, and tool-exposure risks, but they do not turn the service into a safe public internet endpoint. Run SoAI on the local machine or behind a private network boundary. For remote access, prefer an authenticated VPN, such as a WireGuard tunnel or a comparable private-network service.

Security boundaries

Boundary What SoAI enforces Operator responsibility
Accounts and credentials WebUI sessions, inference API keys, and MCP tokens use separate authentication paths. ACL actions limit administrative and tool access. Give each person or client its own credential, grant the smallest useful permission set, set expirations, and revoke access that is no longer needed. See Passwords and credential tools for password and vault guidance.
Browser requests SoAI validates CSRF tokens for unsafe cookie-authenticated requests and rejects unsafe cross-site cookie requests. Origin policy also protects WebSocket and MCP browser connections. Keep allowed origins narrow and protect browser sessions from untrusted extensions, scripts, and devices.
Network transport SoAI supports TLS, secure-cookie policy, trusted proxy networks, CORS policy, rate limits, and configurable bind addresses. Use a firewall or VPN as the main network boundary. Configure TLS and proxy trust for the path clients use.
Tools and code ACL checks, feature switches, MCP exposure lists, workspace roots, and private-network egress checks limit specific capabilities. Treat tools and plugins according to their impact. Some run with the operating-system permissions of the SoAI process and are not sandboxed.

These controls work together. Authentication does not make a dangerous tool harmless, TLS does not reduce the privileges carried by a stolen token, and a reverse proxy does not isolate the SoAI process from its host.

Built-in protections

SoAI applies several controls before an ACL-protected operation or tool runs. Each control covers a specific part of the request or runtime:

Control Enforced behavior Scope and limit
Authentication lifecycle Normal application routes stay unavailable until the first administrator completes setup. Creating the first API-key record makes bearer authentication mandatory on compatible inference APIs. After setup, compatible inference APIs remain unauthenticated while the API-key store has no records. Authentication and API keys explains this state transition.
Credentials and sessions WebUI passwords use Argon2 hashes. SoAI stores inference API keys and MCP personal access tokens as salted HMAC-derived values and fingerprints after showing each secret once. Persisted linked-account and MCP server secrets use encryption tied to the installation key. WebUI sessions expire and can be revoked by device or by account. A password change invalidates the account's earlier sessions. Protect the installation key and its backups because they are part of the password and credential boundary.
Browser requests and responses Session cookies are HttpOnly and SameSite=Lax. SoAI validates CSRF tokens on unsafe cookie-authenticated requests and checks cross-site request metadata plus WebSocket and MCP connection origins. Responses carry content security, anti-framing, MIME-sniffing, referrer, resource, and browser-permission headers. HSTS is sent only for HTTPS requests when enabled. These controls protect the SoAI browser interface; they cannot secure a compromised browser profile, extension, or client device.
Network admission Client-address access rules can reject a request before route handling. Secure-transport policy can reject or redirect plain HTTP. SoAI accepts proxy-derived client and scheme headers only from configured proxy networks. These application checks supplement the host firewall and VPN. They do not replace either boundary.
Resource bounds HTTP request bodies have separate native and compatible-API size ceilings plus a read deadline. Tool families add response, upload, snapshot, script, concurrency, and timeout limits. The bounds reduce memory, oversized-input, and slow-request abuse. They do not authorize a request or guarantee enough capacity for accepted work.
Outbound requests Browser navigation blocks private and loopback destinations while SoAI is online. Other network tools have separate private-network egress switches. The defaults differ by tool. Review each enabled network capability before an agent processes untrusted content.
Plugin admission SoAI checks plugin package structure, hashes, dependencies, and compatibility before launch. Default-on PLUGINS.SECURITY.SAFETY_VALIDATION adds static source and import checks. Admission rejects known-invalid packages. It cannot prove that third-party code is trustworthy, and plugin workers do not provide an operating-system sandbox.
Audit logging The audit log records actors, anonymized client addresses, actions, targets, and sanitized details for events such as ACL denials, API-key changes, configuration mutations, terminal sessions, file operations, and plugin changes. Audit records support review and incident response after an event. They do not prevent the recorded action.

Factory defaults are a starting point

The default SoAI configuration is an operational starting point, not the most restrictive configuration or the recommended final state for an installation that needs stronger security. No single hardened profile fits a local workstation, a shared LAN service, a VPN-only deployment, and an installation with external integrations. Tailor the configuration to the people, clients, networks, data, models, and tools that the instance must serve, and always disable or restrict capabilities that are not required. Resetting to factory defaults is not a hardening action.

Hardening reduces available functionality. Completing the hardening appropriate to a deployment can mean losing access to some SoAI features, such as remote discovery, shell and terminal access, private-network requests, persistent browser sessions, or externally exposed MCP tools. That loss of capability is intentional: each unavailable path is also a path that an unauthorized user, compromised client, unsafe plugin, or prompt-injected model cannot use.

Start with Network and TLS, which documents the default listener behavior and transport settings, then complete the hardening checklist below. Run the WebUI security hardening audit after setup and after meaningful network, access, tool, plugin, or integration changes. Resolve each applicable finding according to the deployment rather than assuming that a shipped default is the safest value for that environment.

Rate limits and quotas

SoAI has separate controls for authentication failures, request frequency, and API-key consumption. WebUI login failures use separate buckets for the client address, the address and username pair, and the username. The default permits 10 failures in 300 seconds, configured by SERVER.WEBUI.LOGIN_SECURITY.AUTH_FAILURE_RATELIMIT.MAX_FAILURES and SERVER.WEBUI.LOGIN_SECURITY.AUTH_FAILURE_RATELIMIT.WINDOW_SECONDS. Invalid bearer authentication on compatible inference APIs uses client-address and token-fingerprint buckets. Its defaults are five failures in 60 seconds, controlled by API.OPENAI.SECURITY.AUTH_FAILURE_RATELIMIT.MAX_FAILURES and API.OPENAI.SECURITY.AUTH_FAILURE_RATELIMIT.WINDOW_SECONDS. A blocked attempt returns 429 with retry guidance.

General API request limiting is controlled by API.OPENAI.RATE_LIMITING.ENABLED and is disabled by default. On a network-exposed deployment, the security hardening audit reports that disabled state. When enabled, SoAI creates a moving-window bucket for each remote client address and configured route path across registered native, MCP, OpenAI-compatible, and Anthropic-compatible routes. The default for non-streaming routes, API.OPENAI.RATE_LIMITING.DEFAULT_LIMIT is 600/minute, while API.OPENAI.RATE_LIMITING.STREAM_LIMIT is 60/minute. Use API.OPENAI.RATE_LIMITING.ROUTERS for router and path-specific policy. Trusted proxy configuration must be correct for SoAI to identify the real client address. The counters live in the running API process and reset after a process restart or a change to the rate-limit rules.

API-key quotas are a different control. They cap requests or tokens over hourly, daily, weekly, or monthly windows for one key or its assigned WebUI user. A quota does not smooth bursts, and request rate limiting does not enforce a usage budget. Use both where several clients share an instance. Neither replaces ACL, authentication, model concurrency limits, a firewall, or a private network boundary.

Prompt injection and untrusted content

Prompt injection is text in a webpage, document, email, code file, retrieved knowledge, or tool result that tries to redirect the model away from the user's request. The dedicated SoAI system prompt page shows the built-in prompt, when SoAI adds it, and how it is prepared for each turn. When that prompt is enabled, it tells the model to treat instructions embedded in user-provided content as data, to treat tool results and external content as untrusted, and to use only the tools SoAI lists in the runtime tool context. Attached content remains separate from SoAI's runtime-owned system and tool context.

SoAI also limits what a successful injection can reach outside the model. Account ACL, runtime policy, and the conversation's mode-specific tool selection determine which tools are available. Plan mode blocks destructive tools and tools without valid destructive metadata. When Require tool approval is enabled, SoAI pauses covered calls and shows the proposed tool input before the user approves or denies execution. These checks are enforced by SoAI rather than left to the model's judgment. In conversations that process untrusted content, approve one call at a time instead of remembering the approval for later calls.

Keep shell tools disabled when an agent does not need to run host commands. Set TOOLS.MCP.SHELL.ENABLED to false, leave shell tools out of the conversation's selected tools, and do not grant Terminal and shell access (TERMINAL_USE) to accounts that do not need it. Disabling shell does not prevent prompt injection itself, but it removes a high-impact path an injected model could use to execute commands with the SoAI process's host permissions. A command blacklist is not a security boundary. See File and shell tools for the installation switch, account permission, and execution boundary.

When an agent can use saved credentials or secret handles, also disable browser JavaScript evaluation unless the task specifically needs it. browser_eval is enabled by default and can read a password after an autofill tool places it in the page. Set TOOLS.MCP.BROWSER.JS_EVAL_ENABLED to false and leave browser_eval out of the selected tools. See Passwords and credential tools for the complete credential boundary.

These measures reduce risk; they do not guarantee that a model will recognize or refuse every hostile instruction. Smaller models and models with weaker instruction following are generally more likely to be diverted, but larger models are not exempt and model size is not a security boundary. Treat user-authored system prompts and workspace instruction files such as SOAI.md or AGENTS.md as trusted configuration, because SoAI intentionally provides them to the agent as instructions. No model choice or prompt makes untrusted content safe by itself; choose the model and its available authority accordingly. See Agent mode, tool approvals, and checkpoints for mode and approval behavior.

Browser ad blocking

Browser ad blocking is enabled by default through TOOLS.MCP.BROWSER.BLOCK_ADS. SoAI intercepts Chromium network requests and applies EasyList rules with request type, document origin, and first-party or third-party context. It starts with a packaged rule set, refreshes it from the configured source, and retains the existing matcher if a refresh fails. Blocking known advertising requests reduces exposure to third-party ad content and malicious advertising while also lowering page noise and resource use.

Ad blocking is defense in depth, not page isolation. EasyList cannot identify every hostile script, tracking request, compromised first-party resource, prompt injection, or unsafe user action. It does not replace the browser's private-network navigation policy, a separate browser profile, least-privilege tools, or human review of consequential actions. See Browser automation tools for browser configuration and authority boundaries.

Browser-backed rendering used by web extraction has its own default-on control, TOOLS.RAG.WEB.BROWSER_RENDER_BLOCK_ADS. The security hardening audit reports a disabled ad-blocking control when the corresponding browser capability is enabled.

Recommended deployment boundary

Keep the WebUI, System API, compatible inference APIs, MCP endpoint, and discovery service off the public internet. A TLS reverse proxy can terminate certificates, apply request limits, and route WebSocket traffic, but it still forwards accepted requests to SoAI. It does not remove application vulnerabilities, compromised credentials, prompt injection, or the host impact of server-side tools. SoAI does not recommend direct internet exposure, even when a reverse proxy sits in front of it.

Use localhost for a single-machine installation. For access from another trusted device, place both devices on a controlled LAN or connect them through an authenticated VPN. WireGuard and services built on the same private overlay model are suitable examples. Restrict the host firewall and bind addresses to that private path, keep the discovery service private, and use TLS when traffic crosses a network you do not control. See Network and TLS for the transport settings.

Security hardening audit in the SoAI WebUI

An administrator with Configuration changes (CONFIG_PATCH) and ACL administration (ACL_ADMIN) selects the Settings button at the right of the header, selects Settings from its menu, then opens Security. The Security hardening audit evaluates the persisted Core configuration, user workspace placement, active administrator device sessions, API keys, and MCP access tokens. Each finding includes a stable issue ID and an explanation, plus configuration or workspace references when they apply. The page presents flagged configuration fields as recommended actions and links workspace findings to Users.

The audit checks network exposure, transport and cookie policy, CORS and trusted proxies, API authentication and rate limiting, logging, terminal and tool access, private-network egress, browser protections, plugin security, MCP server exposure, credential expiration, administrator sessions, and unsafe workspace relationships to the SoAI installation. Some findings apply only when the affected capability is enabled or the deployment is reachable beyond the local machine. The set of checks follows the running SoAI version, so use the report itself as the source for the findings on that instance.

Security hardening findings in backend logs

Before the API and WebUI server starts, SoAI runs the same security audit using the loaded Core configuration. The startup audit includes workspace placement, administrator device sessions, API keys, and MCP access tokens. If it finds an issue, the Core log receives a warning beginning with Security hardening: N issue(s) detected. The warning lists each issue ID and message, followed by any applicable configuration or workspace references. Open Logs from the Settings menu at the right of the header, select the Core source, and search the startup entries for Security hardening. A sidebar link is available only after the user adds Logs under Settings > Theme > Sidebar. Access to Logs requires Log access (LOG_ACCESS).

The configured log location comes from OBSERVABILITY.LOGGING.LOGS_PATH and OBSERVABILITY.LOGGING.MAIN_LOG. SoAI writes the startup security warning only when it finds an issue.

What a green result means

A green result means that the checks implemented by the running version found no issue in the state they inspected. It is a configuration audit, not a penetration test or a guarantee that the deployment is safe. It does not verify the external firewall, VPN, reverse proxy, DNS, client devices, credential storage, third-party plugins, model behavior, or every prompt-injection path. A green result does not make public internet exposure a recommended deployment.

Treat a finding as a concrete action, then decide whether the affected capability should remain enabled at all. Treat a green result as one input to the deployment review. Continue to use private network access, least privilege, individual credentials, current software, trusted plugins, backups, and host-level isolation appropriate to the data and tools the instance can reach.

Protect backups and the installation key

A managed backup includes the primary database, Core configuration, installation encryption key, plugin sidecar configuration, user data, and saved GPU settings by default. A downloaded .tar.gz archive is not an encrypted backup format. Anyone who obtains the archive may gain access to account data, workspace files, provider credentials, and the key needed to decrypt stored secrets. Protect backup files with the same care as the running instance and keep recovery copies outside the SoAI host on access-controlled storage.

The WebUI Verify action checks the managed backup's manifest and recorded contents. A Valid result does not mean that the archive is encrypted, safe to share, or stored in a suitable disaster-recovery location. Review Backup and Restore before relying on a recovery point.

High-impact tools and plugins

MCP tools execute on the SoAI server. Shell commands inherit the operating-system identity of the SoAI process, and MCP shell calls do not pause for the WebUI approval dialog. Server-side file tools reach the token owner's workspace. Browser tools block private-network destinations, but they can still use saved web sessions, upload workspace files, and act on public sites. Linked-account, vault, automation, subagent, persistent-mutation, and resource-intensive tools carry their own data, account, or capacity risks.

Keep high-impact tools out of MCP server mode unless a trusted local client needs them. A suitable case is a local coding agent connected to a local SoAI instance on the same controlled machine. Do not expose these tools to a remote MCP client. A local connection remains unsafe if its model, prompts, repository, browsed content, or other inputs can contain hostile instructions. Review MCP overview and File and shell tools before enabling them.

Plugin workers separate plugin lifecycle state from the main process, but they do not provide an operating-system sandbox. Install plugins only from a source you trust. On SoAI OS, host-management permissions can reach the root-owned management service, so review the SoAI OS security model as well.

Hardening checklist

Work through this checklist before relying on a SoAI instance. It applies to SoAI Core and SoAI OS; host controls increase the consequence of a compromised administrator session.

Accounts and credentials

  1. Complete the setup wizard with a long, unique administrator password and store it in a separate password manager. See Passwords and credential tools.
  2. Open Settings > Users, give administrator access only to operators who need it, and review users after staffing changes. This tab requires User administration (USER_ADMIN).
  3. Open Settings > OpenAI. In OpenAI server API keys, create a separate key for each client, choose an expiration, and revoke the key when that client leaves service. This tab requires API key management (OPENAI_API_ADMIN).
  4. Store each key outside source control. The WebUI shows its plaintext only when SoAI creates it.

Network and transport

  1. Choose a local, LAN, or VPN-only boundary, then restrict the host firewall and bind addresses to it.
  2. Enable TLS with a certificate clients can validate. Test the complete WebUI and API path before enforcing redirects or HSTS.
  3. Replace broad CORS settings with explicit browser origins and preserve WebSocket upgrades at a reverse proxy.
  4. Keep the discovery port off untrusted networks. Discovery helps the WebUI locate the API but does not replace authentication.

Tools and host access

  1. Open Settings > MCP > MCP configuration > Server mode. Set Exposed tools, Exposed resources, and Exposed prompts to only what each client needs, then limit Allowed origins to trusted client origins. These controls require MCP administration (MCP_ADMIN) and Configuration changes (CONFIG_PATCH).
  2. Keep shell, server-side file access, browser sessions, linked accounts, vault access, automations, subagents, arbitrary HTTP methods, and other persistent or resource-intensive tools out of TOOLS.MCP.SERVER_MODE.EXPOSED_TOOLS unless a trusted client specifically needs them. The defaults exclude these high-impact families, and the security audit flags explicit opt-ins on a network-exposed deployment.
  3. Use high-impact MCP tools only for a trusted local client connected to a local SoAI instance. Treat even a same-host client as untrusted when its model, prompts, repository, browsed content, or other inputs can contain hostile instructions.
  4. Disable MCP shell and WebUI terminal access unless operators understand the host impact. MCP shell is controlled by TOOLS.MCP.SHELL.ENABLED, and the WebUI terminal is controlled by SERVER.WEBUI.TERMINAL.ENABLED. A command blacklist is not a security boundary.
  5. Disable TOOLS.MCP.BROWSER.JS_EVAL_ENABLED when browser sessions handle credentials and JavaScript evaluation is not required. The structured typing tool blocks password and one-time-code fields, but arbitrary page JavaScript can read their values after autofill.
  6. On SoAI OS, review SoAI OS administration (HOST_MANAGEMENT_ADMIN) separately from ordinary WebUI access because it authorizes privileged actions through the root-owned management service.
  7. On SoAI OS, keep network safe-apply, SSH recovery, and local-console access available before changing remote access.

Audit and recovery readiness

  1. Open Settings > Security and resolve every hardening finding that applies to the deployment.
  2. Check the Core startup log after configuration, workspace, network, plugin, or upgrade changes.
  3. Schedule backups and rehearse a restore using the data and configuration you expect to recover.
  4. Keep enough disk space for model downloads, backups, package updates, and temporary files.
  5. Read task results and audit events after driver, storage, update, network, or user changes. Do not treat an accepted task as a completed task.
  6. Keep Operational runbooks, Authentication and API keys, and Network and TLS with the operator handoff.

Related documentation