Use the SoAI WebUI for ordinary lifecycle work while SoAI is reachable. In the sidebar, open Power and
choose Restart application or Shut down application. The Power page is available
only to administrators with the System power control (SYSTEM_POWER) action. See
Administration overview for lifecycle permissions. Use the launcher when SoAI
is stopped, the WebUI cannot be reached, or a terminal workflow is required.
Use the launcher for the installed edition
SoAI Core on Linux uses ./soai.sh. A Core installation in the
default macOS (experimental) location uses
/Applications/SoAI/soai.command; a complete local source tree also contains ./soai.sh.
SoAI OS uses ./soai_os/soai_os.sh, and a Windows
installation uses soai.exe. Use the launcher for the installed edition. See SoAI products and
editions for the edition boundary.
A default Windows installation keeps soai.exe in
C:\Program Files\SoAI and does not put it on the command path, so open a terminal in that folder or
call the launcher by its full path before using any command on this page. Starting SoAI needs none of that, because
the installer writes SoAI to the Start Menu and the desktop and that shortcut runs the same
launcher.
Control and diagnose the running process
Running the launcher without a command starts SoAI. --start is the explicit form. Use
--start-no-browser when the launcher must not open a browser window, which the
Windows launcher never does because it shows the WebUI in its own
application window instead. --status reports the matching instance state and any runtime details the
launcher can read.
# SoAI Core ./soai.sh --start-no-browser ./soai.sh --status # SoAI OS ./soai_os/soai_os.sh --start-no-browser ./soai_os/soai_os.sh --status
Stop or restart from a terminal
Use the same edition launcher for --stop and --restart. These commands manage a matching
running instance and do not start a missing one.
# Choose the command for the installation you are managing ./soai.sh --stop ./soai.sh --restart ./soai_os/soai_os.sh --stop ./soai_os/soai_os.sh --restart
Collect startup diagnostics
On Linux and macOS, put --debug first to enable shell tracing for the POSIX launcher. Use
--verbose for detailed bootstrap logging. Shell tracing can reveal command arguments and paths, so
remove sensitive values before sharing its output.
# POSIX launcher tracing ./soai.sh --debug # Detailed bootstrap logging ./soai.sh --verbose
Recover access and repair the runtime
An Administrator with User administration (USER_ADMIN) can select the Settings button at the
right of the header, select Settings from its menu, select Users, and choose
Password for the account. A Standard account has no self-service Users-tab path.
The Administration overview covers user management and access.
The POSIX launchers also provide --reset-user-password USERNAME for a locked-out account. The Windows
release launcher does not expose that interactive recovery command. Read Reset and account
recovery before using it.
Repair the managed runtime
Run install-deps from a stopped installation to provision or repair the managed runtime, required
packages, and runtime artifacts. It refuses to run while the matching installation is starting or running. Use the
release installer to choose an installation target. --target is not valid with
install-deps.
# SoAI Core ./soai.sh install-deps # SoAI OS ./soai_os/soai_os.sh install-deps # SoAI on Windows soai.exe install-deps
Configure the environment and offline setup
SOAI_CONFIG_PATH selects the active configuration file. Relative values are resolved from the
installation root; the default is data/config/config.yaml. Prefer the WebUI configuration controls
for normal settings changes, then use the path override only when the deployment requires a different file.
SOAI_NO_BROWSER suppresses browser opening when it has a non-empty value, and
SOAI_BOOTSTRAP_VERBOSE=1 enables verbose bootstrap logging. The POSIX launcher also accepts
SOAI_DEBUG=1. Runtime directories can be redirected with SOAI_STATE_DIR,
SOAI_VENV_PATH, SOAI_TMP_DIR, SOAI_PIP_CACHE_DIR, and
PLAYWRIGHT_BROWSERS_PATH. Set any override before launch and ensure the service account can write to
it. POSIX process locks remain under the installation's data/state/locks directory.
Prepare an offline installation
When SYSTEM.RUNTIME.STAY_OFFLINE
is enabled, bootstrap does not download missing dependencies or browser artifacts. On a new installation, run
install-deps with network access before enabling offline mode.