Skip to main content
The exec tool executes shell commands with built-in safety guards to prevent dangerous operations.

​
exec

Execute a shell command and return its output.

​
Input Parameters

​
command
string
required
The shell command to execute. Uses sh -c on Unix/Linux or powershell on Windows.
​
working_dir
string
Optional working directory for the command. Defaults to the tool’s configured working directory.

​
Response

Returns combined stdout and stderr output.
​
output
string
Command output with format:
{stdout}
STDERR:
{stderr}
If command fails, includes exit code:
{output}
Exit code: {error}

​
Usage Examples

Basic command: 
{
  "command": "ls -la"
}
With working directory: 
{
  "command": "npm install",
  "working_dir": "/workspace/frontend"
}
Multiple commands: 
{
  "command": "git add . && git commit -m 'Update' && git push"
}

​
Output Behavior

  • Maximum output length: 10,000 characters
  • Longer output is truncated with message: ... (truncated, {N} more chars)
  • Both stdout and stderr are captured and returned
  • Empty output returns: (no output)

​
Error Conditions

Validation errors:
  • command is required - Missing command parameter
Safety guard blocks:
  • Command blocked by safety guard (dangerous pattern detected) - Dangerous command detected
  • Command blocked by safety guard (not in allowlist) - Command not in allowlist (if configured)
  • Command blocked by safety guard (path traversal detected) - Path traversal with workspace restriction enabled
  • Command blocked by safety guard (path outside working dir) - Absolute path outside workspace
Execution errors:
  • Command timed out after {duration} - Command exceeded timeout (default: 60s)
  • Command output with exit code for failed commands

​
Safety Guards

​
Dangerous Pattern Detection

The following patterns are automatically blocked:
PatternDescriptionExample
rm -rf / rm -frRecursive force deleterm -rf /
del /f / del /qWindows force deletedel /f C:\\*
rmdir /sWindows recursive deletermdir /s C:\\Users
format / mkfs / diskpartDisk formattingformat C:
dd if=Direct disk writedd if=/dev/zero of=/dev/sda
> /dev/sd[a-z]Write to disk deviceecho x > /dev/sda
shutdown / reboot / poweroffSystem power operationsshutdown -h now
Fork bomb patternSelf-replicating process:(){ :|:& };:

​
Workspace Restriction

When restrictToWorkspace=true:
  • Commands containing ../ path traversal are blocked
  • Absolute paths in commands are validated to be within workspace
  • Prevents reading/writing files outside the working directory
Example: 
// With workspace: /home/user/project
// restrictToWorkspace: true

{"command": "cat ../../etc/passwd"}
// Error: Command blocked by safety guard (path traversal detected)

{"command": "cat /etc/passwd"}
// Error: Command blocked by safety guard (path outside working dir)

{"command": "cat ./config.json"}
// Allowed: Path within workspace

​
Allowlist Mode

Optionally configure an allowlist of permitted command patterns: 
tool.SetAllowPatterns([]string{
  `^git `,       // Only git commands
  `^npm `,       // Only npm commands  
  `^docker `,    // Only docker commands
})
When allowlist is configured, ONLY matching commands are permitted.

​
Configuration Options

​
Timeout

Default: 60 seconds 
tool.SetTimeout(120 * time.Second) // 2 minutes
Commands exceeding the timeout are terminated and return: 
Command timed out after {duration}

​
Platform Behavior

Linux/macOS:
  • Uses sh -c "{command}"
  • POSIX-compliant shell execution
Windows:
  • Uses powershell -NoProfile -NonInteractive -Command "{command}"
  • PowerShell execution environment

​
Test Coverage

From shell_test.go: Success cases:
  • Basic command execution with output capture
  • Custom working directory
  • Stderr capture alongside stdout
Failure cases:
  • Non-existent command/path returns error with exit code
  • Timeout terminates long-running commands
  • Dangerous commands blocked by safety guards
  • Path traversal blocked with workspace restriction
Output handling:
  • Long output (>10,000 chars) is truncated
  • Empty output returns placeholder message

Build docs developers (and LLMs) love

Get started for freeTalk to us