Shell Tool

Execute shell commands with security sandboxing

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:

Command Validation

Commands are validated against:

• Blocked command patterns (rm -rf /, dd, mkfs, etc.)
• Dangerous flag combinations
• Path traversal attempts
• Network access restrictions (when configured)

Environment Variables

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

Execution Limits

• 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

Related

• Tool Trait
• Security Policy
• Creating Tools Guide