Skip to main content
The shell tool allows agents to execute shell commands with configurable timeout, working directory restrictions, and safety guards against destructive operations.

​
Tool Name

exec

​
Description

Execute a shell command and return its output. Use with caution.

​
Parameters

​
command
string
required
The shell command to execute
​
working_dir
string
Optional working directory for the command. If not provided, uses the tool’s configured working directory or current working directory.

​
Return Value

Returns a string containing:
  • Standard output (stdout)
  • Standard error (stderr) prefixed with “STDERR:”
  • Exit code (if non-zero)
  • Error messages for timeouts or blocked commands
Output is truncated to 10,000 characters if longer.

​
Configuration

The ExecTool can be configured with the following options: 
ExecTool(
    timeout=60,                      # Command timeout in seconds
    working_dir=None,                # Default working directory
    deny_patterns=None,              # Regex patterns to block
    allow_patterns=None,             # Allowlist patterns (if set, only these are allowed)
    restrict_to_workspace=False,     # Block path traversal outside working dir
    path_append=""                   # Additional PATH entries
)

​
Safety Guards

The tool includes built-in safety patterns that block dangerous commands:
  • rm -rf, rm -fr - Recursive file deletion
  • del /f, del /q - Windows file deletion
  • rmdir /s - Windows directory removal
  • format, mkfs, diskpart - Disk formatting
  • dd if= - Disk operations
  • shutdown, reboot, poweroff - System power commands
  • Fork bombs and similar patterns
Commands matching deny patterns return an error without execution.

​
Examples

​
Basic Command Execution

{
  "command": "ls -la"
}
Returns: 
total 48
drwxr-xr-x  12 user  staff   384 Mar  6 10:30 .
drwxr-xr-x   5 user  staff   160 Mar  5 14:20 ..
...

​
Command with Working Directory

{
  "command": "git status",
  "working_dir": "/path/to/repo"
}

​
Command with Error Output

{
  "command": "cat nonexistent.txt"
}
Returns: 
STDERR:
cat: nonexistent.txt: No such file or directory

Exit code: 1

​
Blocked Command

{
  "command": "rm -rf /"
}
Returns: 
Error: Command blocked by safety guard (dangerous pattern detected)

​
Command Timeout

{
  "command": "sleep 120"
}
Returns (after 60 seconds): 
Error: Command timed out after 60 seconds

​
Implementation

See nanobot/agent/tools/shell.py:12 for the full implementation.

Build docs developers (and LLMs) love

Get started for freeTalk to us