SoAI exposes one main HTTP API and a small discovery service used by the WebUI to find the API. The default main
port is 5090. Discovery tries ports 7950 through 7960 and reports the API
port, URL scheme, and edition state. Both
SERVER.HTTP.NETWORK.HOST and
SERVER.HTTP.NETWORK.DISCOVERY_HOST
default to 0.0.0.0, which listens on all interfaces. Review those values and
SERVER.HTTP.NETWORK.PORT before
exposing the service. In the SoAI WebUI, an administrator with the Configuration changes (CONFIG_PATCH) permission selects the
Settings button at the right of the header, chooses Settings, selects
Advanced in the page header, opens Server, changes the fields in the
Network group, and selects Save.
HTTP and HTTPS
TLS is off by default. Enable it with
SERVER.HTTP.SSL.TLS_ENABLED. With user-supplied certificates, provide both
SERVER.HTTP.SSL.CERT_FILE and
SERVER.HTTP.SSL.KEY_FILE; SoAI rejects an incomplete pair. SoAI creates a local self-signed certificate only when TLS is enabled and both
fields are empty. Browsers and clients must trust that certificate or use a certificate issued for the deployment
name. On Windows, that certificate is kept in the installation's
protected data folder; on other platforms, it is kept in the home folder of the account that runs SoAI.
SoAI requires TLS 1.2 or newer for the local TLS context and disables TLS compression. With a user-supplied server
certificate and key, a configured CA file also makes SoAI require a client certificate trusted by that CA. It does
not make SoAI's server certificate trusted by clients. Use
SERVER.HTTP.SSL.CA_FILE and
SERVER.HTTP.SSL.KEY_PASSWORD only
with a complete certificate and key configuration.
Transport policy, proxies, and CORS
SERVER.HTTP.SECURITY.REQUIRE_SECURE_TRANSPORT
rejects insecure requests, while
SERVER.HTTP.SECURITY.FORCE_HTTPS_REDIRECT
redirects them only when local TLS is enabled or trusted proxy headers are active. HSTS is controlled by
SERVER.HTTP.SECURITY.ENFORCE_HSTS. SoAI sends HSTS only on HTTPS responses. Test redirects and certificate trust before enabling HSTS for a hostname
you cannot quickly recover.
If a TLS reverse proxy fronts SoAI, preserve the WebUI WebSocket upgrade and configure both
SERVER.HTTP.PROXY.ENABLE_HEADERS
and
SERVER.HTTP.PROXY.TRUSTED_NETWORKS. Proxy headers are inactive until header support is enabled and at least one trusted network is listed. Do not
trust forwarded headers from arbitrary clients.
CORS is controlled by
SERVER.HTTP.CORS.ALLOWED_ORIGINS
and
SERVER.HTTP.CORS.ALLOW_CREDENTIALS. An empty allow-list does not enable cross-origin browser requests. If you add a wildcard or broad origin policy,
replace it with the exact browser origins you use before exposing the service to other networks.
Binding and reverse proxies
Keep the discovery service on a trusted network and protect the main API with TLS, authentication, and a private
network boundary. A reverse proxy does not make public internet exposure a recommended deployment. Prefer a VPN,
such as WireGuard or a comparable private-network service, for remote access. See
Security hardening for the deployment policy and audit limits. For an
additional application-level policy, review
SERVER.HTTP.ACCESS_CONTROL.IP_WHITELIST
and
SERVER.HTTP.ACCESS_CONTROL.IP_BLACKLIST.
Public origin for messaging
Telegram and WhatsApp callbacks require a provider-reachable public HTTPS origin. Discord uses an outbound Gateway
connection and does not require a public endpoint. Agent questions, tool approvals, and secure secret links require
an HTTPS origin for all three providers, but a Discord-only origin can remain private if the messaging account owner
can reach it. An administrator with Configuration changes (CONFIG_PATCH) selects the
Settings button at the right of the header, chooses Settings, selects
Advanced, opens Server, sets Public origin, and selects
Save. The setting is
SERVER.PUBLIC_ORIGIN.
Enter the HTTPS base address without a provider callback path. SoAI builds the callback and authenticated Chat links
from it. Publish /api/v1/messaging/telegram/webhook for Telegram and
/api/v1/messaging/whatsapp/webhook for WhatsApp, preserving the query string that SoAI adds. The WebUI,
WebSocket, and other API routes do not need to be public for provider message delivery. If the account owner will
open secure Chat links remotely, give that owner private access through a VPN or equivalent network boundary. See
Connect messaging apps to SoAI for provider setup.
Exposing SoAI directly to the public internet is not recommended. Restrict public routing to the callback routes and keep the remaining interface behind a firewall or VPN. Read Security hardening before configuring a public callback.