File and shell tools | SoAI Documentation

Eleven tools let an agent work with files and run commands: seven read and edit files inside a folder you choose, while four drive a real interactive shell on the host. The risk differs sharply between those groups, so SoAI applies separate controls to each one.

In the SoAI WebUI, let an agent use these tools by selecting Chat configuration in the chat header, then Tools. Turn on Tools enabled, choose tools for Chat mode, Plan mode, or Execute mode, and select Save. The account needs MCP usage (MCP_USE) and the selected model must support tool calling. Shell calls also require Terminal and shell access (TERMINAL_USE). The tool runtime must be enabled (TOOLS.MCP.ENABLED).

Choosing the folder an agent works in

File tools operate inside one folder, the same one the Files page shows for your account. To point a single conversation somewhere else, open Chat configuration, go to the Files tab, and use the Folder section: Change folder picks a new one, Inherit default puts it back. SoAI rejects paths that leave that folder and resolves relative paths inside it.

An administrator with User administration (USER_ADMIN) selects the Settings button at the right of the header, then Settings and Users, to set an account's default folder. In the Users section, find the account and select Folder. Pointing several accounts at the same folder gives them a shared workspace.

This boundary covers the file tools only. The shell tools run commands as the SoAI process (outside that folder boundary) and can reach anywhere on the host that the process can.

Reading

read_file reads UTF-8 text: source, config, logs. It has three modes.

slice, the default, returns a run of lines chosen with offset and limit. limit defaults to 2000 lines.
indentation centres the view on an anchor line and follows the indentation structure around it, which gets a whole function without the model guessing line numbers.
raw reads the entire file and rejects the slicing arguments outright.

In the first two modes, render chooses between unnumbered output, which is what a patch needs, and numbered output for display. For images, audio, video, and PDFs, reach for the Media reading tools instead.

list_dir walks a directory to a given depth. glob_files matches paths by pattern and sorts by name or modification time. grep_files searches file contents through a managed ripgrep build, with include filters, context lines before and after, case folding, multiline matching, and a choice of output modes for content, matching file names, or counts.

Writing

Tool	Use it for	Guards
`apply_patch`	Several edits across several files in one call	Snapshots support rollback if an operation fails
`replace_in_file`	Swapping an exact string	`expected_replacements` makes the call fail if the count differs; `replace_all` and `allow_noop` cover the other cases
`write_file`	Creating a file, or replacing one whole	`overwrite` must be set before it clobbers an existing file

write_file and replace_in_file both take dry_run, which reports what would change and writes nothing. Every edit that does land shows up in the transcript as an expandable Code diff, so you can read what the agent changed without leaving the chat.

The catalog marks all three destructive, so Plan mode refuses them. When Require tool approval is on, the approval dialog appears before each call.

Read before write

SoAI requires an agent to read a file before editing it. The guard catches the failure mode where a model rewrites a file from memory and silently drops everything it did not remember. It is on by default. To turn it off, an administrator with Configuration changes (CONFIG_PATCH) selects the Settings button at the right of the header, then Settings. Select Advanced in the Settings page header. The page becomes Advanced settings and the control changes to Basic. Search for TOOLS.MCP.FILE_GUARD_READ_BEFORE_WRITE.ENABLED, set it to false, and select Save.

The shell

Shell commands run on the SoAI host as the operating-system account that runs SoAI. They do not run on the MCP client. Shell tools are excluded from the default server-mode exposure list; adding them to TOOLS.MCP.SERVER_MODE.EXPOSED_TOOLS is an explicit high-impact opt-in. On a network-exposed deployment, that opt-in appears in the WebUI security audit. An MCP call does not receive the WebUI terminal approval dialog.

Expose shell and server-side file tools only within the local trust boundary described in Security hardening. A green audit does not make remote MCP exposure safe, and a same-host connection remains unsafe when prompts, models, repository content, or other inputs are untrusted.

shell runs a command in a real pseudo-terminal and returns a session ID along with the output. The session stays alive, so a later call can write to the same prompt instead of starting over. The persistent session lets an agent run interactive programs: it can start Python, answer a password prompt, or drive an installer that expects a keystroke.

Tool	What it does
`shell`	Runs `cmd`, optionally in a `workdir`, under a login shell, with a `tty` of a given size. `run_in_background` returns immediately and leaves it running.
`shell_output_read`	Pages through a session's transcript, from the start or `from_end`.
`shell_output_search`	Searches a session's transcript for a string.
`shell_write_stdin`	Sends `chars` or named `keys` to a live session, and can resize its terminal.

Long-running commands do not have to block the turn. With run_in_background, the agent starts a build or a test suite, does something else, then comes back with shell_output_read. max_output_tokens caps each response, and the two reader tools page through the rest.

While a command runs you can stop it yourself. The tool call in the transcript carries a Stop command control.

Shell controls

TOOLS.MCP.SHELL.COMMAND_BLACKLIST exists and is empty by default. Filling it in blocks the commands you name. Treat it as a guard against a model doing something careless, not as a security boundary. It matches command text, and anything the SoAI process can do on the host, a shell call can still do by some other spelling.

Installation switch

TOOLS.MCP.SHELL.ENABLED is true by default. An administrator with Configuration changes (CONFIG_PATCH) selects the Settings button at the right of the header, then Settings. Select Advanced in the Settings page header. The page becomes Advanced settings and the control changes to Basic. Search for the key, set it to false, and select Save. All four shell tools then refuse to run and name the key in the error.

Account permission

Every shell tool checks the caller's Terminal and shell access (TERMINAL_USE) permission at call time. An administrator with ACL administration (ACL_ADMIN) selects the Settings button at the right of the header, then Settings and ACL, to grant it. Administrators hold it by default. It is absent from the Standard user's default actions, although MCP usage (MCP_USE) is present. Terminal appears in the default sidebar for administrators and for Standard users granted this permission, unless that user has hidden the item in their sidebar settings. The direct route is /#terminal. A permitted user can also use shell tools through an agent.

For the interactive terminal a person drives directly, see Terminal. The Hardening checklist covers locking this down.

Read a skill's supporting files with skill_read. To copy the full package into the workspace, select skill_materialize under Chat configuration > Tools > Execute mode and save. The assistant can then activate the skill and request a copy, subject to write approval. Running a copied script is a separate action using an allowed execution tool and the runtime specified by the skill.