Use the SoAI WebUI for everyday administration: first setup, accounts, backups, network access, and operational checks. Use the HTTP API reference when you need to automate the same operations.
Set up administration and access
A new installation has no accounts. Open the WebUI and complete the setup wizard to create the first
administrator. Until that step finishes, authenticated application routes return setup_required and
the WebUI continues to show the wizard. The first account becomes an administrator automatically.
Manage users and permissions
An administrator whose ACL grants User administration (USER_ADMIN) selects the
Settings button at the right of the header, then selects Settings from its menu.
Open Users and select
Create user. Enter the account details, then choose Administrator or
Regular user in the role prompt. Administrators receive the administrative access policy; regular
users can use only the actions granted to them.
ACL policy applies actions to roles, not individual accounts. Before changing a role-wide permission or promoting an account, read Access control for the WebUI workflow, defaults, fixed actions, and complete permission table.
Protect and expose the instance
An administrator whose ACL grants Backup administration (BACKUP_ADMIN) selects the
Settings button at the right of the header, then selects Settings from its menu.
Open Backup and select Create backup. After it completes as valid, select
Verify. Valid backups also enable Restore; every listed backup has
Download and Delete unless another backup operation is running. Treat
Restore as a recovery operation: read the restore confirmation and the
Restore guide before applying it to a working instance.
Backups run every 24 hours by default and retain up to seven backups for up to 720 hours. By default, the enabled
targets are the database, core configuration, encryption key, plugin configuration, user data, and GPU settings.
User data covers the configured files and wallpaper storage. Logs are not a default backup target;
enable DATA.BACKUP.TARGETS.LOGS if
you need them in a backup. Models and backend runtimes are not backup targets.
The backup process records its selected targets in a manifest and checks SQLite integrity before treating a database backup as complete. Review the Backup page for target configuration, retention, and a recovery checklist.
Network access and reverse proxies
The main API listens on port 5090 by default. Change it with
SERVER.HTTP.NETWORK.PORT. SoAI also
uses the discovery range 7950 through 7960 so the WebUI can find a non-default API port
during startup.
No browser origins are allowed cross-origin by default:
SERVER.HTTP.CORS.ALLOWED_ORIGINS
starts as an empty list. Add only the exact browser origins that need cross-origin access. If SoAI runs behind a
reverse proxy, forward WebSocket upgrade traffic. The WebUI uses its WebSocket connection for live state and does not
fall back to polling when that connection is unavailable. See Network and TLS for
TLS, public origins, and proxy headers.
Monitor health and control the lifecycle
Use Metrics in the sidebar and Logs in the Settings menu at the
right of the header for routine diagnosis. Logs can also be added to the sidebar from
Settings > Theme > Sidebar: at Visible pages, select Edit,
enable Logs, then select Save. The configured application log location is controlled by
OBSERVABILITY.LOGGING.LOGS_PATH.
The audit log records security-relevant operations such as sign-in activity, API-key changes, and terminal session
lifecycle events.
For a plugin that fails to start or becomes unavailable, check its status in Plugins first, then review its logs and the failure model in Resilience and self-healing. Follow Reset an open circuit or Make a quarantined plugin available again, depending on the state. Avoid resetting the whole instance to resolve an isolated plugin problem.