Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HKUDS/nanobot/llms.txt

Use this file to discover all available pages before exploring further.

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