The Terminal page opens an interactive shell on the SoAI host. It is not a sandbox (commands run with the operating system permissions of the SoAI process). Use it for host work only when that level of access is appropriate.
Who can open Terminal
The Terminal page requires an authenticated account with Terminal and shell access
(TERMINAL_USE). Administrators receive that action by default. An administrator whose ACL grants
ACL administration (ACL_ADMIN) can grant or remove it for a regular account. In the SoAI WebUI, select the
Settings button at the right of the header, then select Settings from its menu and
open ACL. The Terminal sidebar entry appears for every account granted the action. Each permitted
user can choose whether to show or hide it with the sidebar customization control in Settings. A user without the
action does not receive the navigation entry and sees an access-denied message if navigation is attempted.
The feature also requires
SERVER.WEBUI.TERMINAL.ENABLED,
which is on by default. An administrator whose ACL grants Configuration changes
(CONFIG_PATCH) can select the Settings button at the right of the header, then select
Settings from its menu. Select Advanced in the page header, open
Server, use Search settings... to find the path, and select
Save. The title changes to Advanced settings and the
header control becomes Basic. Disabling it prevents new terminal sessions even for an account that
has the action.
Use an interactive session
Open Terminal from the sidebar. The WebUI creates an interactive PTY session over the main SoAI WebSocket and starts the host's configured default shell. Input, output, and window resizing stay in that session. A WebSocket connection can have one active PTY session at a time.
The terminal toolbar provides Increase text size, Decrease text size, and Clear terminal. Use the page header's Open in new window action when a detached terminal is more convenient. If a foreground command is still running, navigating away shows a confirmation because leaving terminates that terminal session.
Session behavior and limits
SoAI sends PTY input and output through /api/v1/system/ws; it does not expose a separate one-shot
command endpoint for the WebUI. New sessions use an 80 by 24 terminal size when no dimensions are supplied. The
server limits received dimensions to 500 columns and 200 rows. Closing the session or leaving the page closes the
PTY.
Audit and security
SoAI records terminal session connection and disconnection events in the audit log. It does not parse every command
typed into the interactive shell. Give Terminal and shell access (TERMINAL_USE) only
to accounts that should have the same host access as the SoAI process, and remove the action when that access is no
longer needed.