Tools & Sandbox Safety
rupi includes seven core built-in tools for agent coding tasks, designed around strict confinement, bounded output, and approval contracts.
Built-In Tools
1. read
- Purpose: Inspect files within the workspace.
- Parameters:
path(relative or absolute). - Behavior: Verifies that the resolved path resides strictly within the workspace root (
--cwd). If outside, the request is immediately denied with an out-of-bounds error.
2. write
- Purpose: Create or completely overwrite a file.
- Parameters:
path,content. - Classification: Mutating. Refused unless auto-approval is enabled.
3. edit
- Purpose: Perform structured search-and-replace edits on an existing file.
- Parameters:
path,old_text,new_text. - Classification: Mutating. Ensures atomic replacement without unexpected collateral drift.
4. grep
- Purpose: Search workspace text with bounded results.
- Parameters: Search pattern and path/options.
- Classification: Read-only by default; search-directory expansion is separately policy-controlled.
5. exec
- Purpose: Execute shell commands within the workspace directory.
- Parameters:
command. - Classification: Mutating.
exec uses the platform shell: cmd.exe /C on Windows and sh -c on Unix-like
systems. For a known executable, prefer process so each argument remains one
argv value and is not reinterpreted by shell quoting or expansion.
On Windows, use dir rather than Unix ls when a shell listing is needed. For a known
program, pass its executable and arguments directly to process; use cmd.exe with
/C only when the command genuinely needs shell syntax.
6. process
- Purpose: Execute a program directly with an explicit argument list.
- Parameters:
program, optionalargs,cwd, andtimeout_ms. - Classification: Mutating — an arbitrary program may change workspace or external state.
Safety Guarantees
Workspace Confinement Root
At startup, the --cwd directory is canonicalized. File operations are checked with
realpath resolution so traversal and outward-pointing symlink components cannot escape
the workspace. Explicit policy flags are required to widen read, search, or write scope.
Mutating Tool Guard
Mutating tools (write, edit, exec, process) cannot run automatically unless explicitly permitted in your configuration:
{
"tools": {
"auto_approve_mutating": true
}
}
If auto_approve_mutating is false (the default), mutating requests return an
explicit refusal event, preventing unintended side effects. Enable it only for a
trusted workspace.
Process Boundaries
Neither tool is an OS-level sandbox. If running untrusted agent code, execute rupi
within Docker, a VM, or an isolated container sandbox.