SoAI keeps durable state under one system-data root by default. The database, managed files, model downloads, plugin runtimes, logs, backups, knowledge indexes, browser state, and WebUI media use separate paths beneath that root. Changing a path does not move existing data.
Understand storage paths
SYSTEM.PATHS.BASE is the installation
base used to resolve base-relative paths, with an empty value selecting the installation directory.
SYSTEM.PATHS.SYSTEM_DATA defaults
to data under that base, and most state paths are then resolved under the system-data directory. Every
path listed below requires a restart after it changes.
Know what each durable path owns
| Stored data | Configuration path | Factory-relative location |
|---|---|---|
| Primary database | DATA.DATABASE.PATHS.SYSTEM_DB | database/soai.db |
| Encryption key for protected values | SYSTEM.PATHS.SYSTEM_ENCRYPTION_KEY | secret.key |
| Managed user files | DATA.FILES.PATHS.FILES_STORAGE | files |
| Downloaded model files | MODELS.MANAGER.PATHS.MODELS | models |
| Managed plugin backends | PLUGINS.PATHS.BACKENDS | backends |
| Plugin environments | PLUGINS.PATHS.VENVS_ROOT | plugins/venvs |
| Application logs | OBSERVABILITY.LOGGING.LOGS_PATH | logs |
| Managed backups | DATA.BACKUP.BACKUPS_PATH | backups |
| Knowledge vector index | TOOLS.RAG.CHROMA_PATH | chroma_rag |
| Knowledge sparse index | TOOLS.RAG.SPARSE_INDEX_DIR | rag_sparse_index |
| Browser cookies and origin storage | TOOLS.MCP.BROWSER.STORAGE_STATE_DIR | browser-storage-state |
| Persistent browser profiles | TOOLS.MCP.BROWSER.USER_DATA_DIR_BASE_DIR | browser-user-data |
| Shared wallpaper | SERVER.WEBUI.WALLPAPER_STORAGE_PATH | wallpaper |
Installed .soaiplugin packages are different. Their
PLUGINS.PATHS.PLUGINS path is
resolved under the installation base, not under system data.
Skill packages, supporting files, and conversation selections are stored in the primary database, rather than installed into a workspace or a separately configured skills folder. Removing a skill stops its use by future requests. Its content can remain retained while already accepted or queued work still uses it; that retained content counts toward the account's library storage limit until the work finishes.
Plan and relocate data
Model files and plugin runtimes usually dominate storage use. Managed files, knowledge indexes, browser profiles, logs, metrics history, and backups grow with use. A backup can temporarily require substantial free space in both its source and destination. Keep the database and encryption key together in the recovery plan; protected values cannot be recovered from the database alone.
SoAI reserves disk space before supported large writes and rejects work that would violate its reserve. See Capacity planning for reserve settings and workload sizing.
Relocate data safely
Editing Advanced Settings requires Configuration changes
(CONFIG_PATCH). Choose a maintenance window:
the safe sequence saves the new path, stops SoAI before the restart, copies the data, and then starts SoAI with the
saved path. Do not use SoAI between saving the path and stopping the service.
- Create and verify a SoAI backup. Export a copy off the host.
- In the SoAI WebUI, select the Settings button at the right of the header, then Settings. Select Advanced in the page header.
- Paste the complete configuration path from the table above into the settings search. Confirm that the result is the path you intend to move.
- Enter the destination and select Save. Use an absolute path when ownership or mount boundaries would otherwise be unclear.
- When Restart SoAI appears, do not select it yet. Stop SoAI immediately with the launcher for the installed edition.
- Copy the complete source to the saved destination, preserving permissions. Keep the original copy.
- Start SoAI with the same edition launcher. The saved path takes effect during startup.
- Wait for readiness, sign in, and verify the affected models, files, knowledge collections, browser state, plugin state, or logs.
- Remove the old copy only after the new location and a restore test are known to work.
Do not change a path while the service is writing to it, and do not assume a configuration edit migrates existing content. For a complete move between installations, prefer the supported backup and restore workflow over manual selection of database-related files.
Related documentation
- Skills
- Backup and Restore for contents, verification, and restore scope.
- Configuration for every managed path.
- Privacy and data handling for retention and provider boundaries.