Skip to main content
The shell tool allows agents to execute shell commands in the workspace directory with comprehensive security controls.

​
Overview

The Shell tool provides:
  • Command execution with 60-second timeout
  • Output size limits (1MB max)
  • Environment variable filtering
  • Security policy validation
  • Syscall anomaly detection (optional)
  • Cross-platform support (Linux, macOS, Windows)

​
Parameters

​
command
string
required
The shell command to execute. Validated against security policy.

​
Example

{
  "command": "ls -la"
}

​
Response

​
output
string
Combined stdout and stderr from the command execution
​
exit_code
integer
Command exit code (0 for success)

​
Security

The shell tool enforces multiple security layers:
Commands are validated against:
  • Blocked command patterns (rm -rf /, dd, mkfs, etc.)
  • Dangerous flag combinations
  • Path traversal attempts
  • Network access restrictions (when configured)
Only safe environment variables are passed:
  • PATH, HOME, TERM, LANG, USER, SHELL
  • Windows: USERPROFILE, SYSTEMROOT, TEMP
  • Custom additions via shell_env_passthrough config
  • Never passes API keys or credentials
  • Timeout: 60 seconds hard limit
  • Output: 1MB maximum (truncated if exceeded)
  • Working Directory: Scoped to workspace
  • Syscall Monitoring: Optional anomaly detection

​
Configuration

Configure shell tool behavior in config.toml: 
[security]
shell_enabled = true
blocked_commands = [
    "rm -rf /",
    "dd if=",
    "mkfs",
    "format"
]
shell_env_passthrough = ["CI", "BUILD_ID"]

​
Source Code

Implementation: src/tools/shell.rs

Build docs developers (and LLMs) love

Get started for freeTalk to us