Skip to main content
The shell tool lets the agent execute shell commands on the host system. Because shell access is powerful, IronClaw applies two layers of protection before any command runs: environment scrubbing and command injection detection.

​
Configuration

Without this setting, the shell tool is not registered and is invisible to the LLM.

​
Environment Scrubbing

Before executing any command, the shell tool builds a sanitized environment. Sensitive variables are removed entirely — they are never present in the process environment when the command runs. Variables that are scrubbed: Variables that are preserved: Why this matters: Without scrubbing, a command like env or printenv — or a compromised binary on PATH — could dump all environment variables, including API keys, to stdout. The shell tool prevents this by ensuring secrets are never in the environment to begin with.

​
Command Injection Detection

The sanitizer analyzes every command before execution and blocks patterns commonly used in injection attacks.

​
Blocked Patterns

​
Blocked Examples

​
Allowed Examples

Pipe (|) within a single command is allowed because it does not chain independent commands — it passes stdout of one program to stdin of another within the same execution context.

​
Output Sanitization

Shell output passes through the Safety Layer before reaching the LLM:
  1. Leak detector — Scans for secret patterns in stdout/stderr. If output contains something that looks like an API key or token, it is redacted.
  2. Sanitizer — Escapes control characters and other dangerous content.
The output is wrapped before the LLM sees it:

​
Security Considerations

When a job involves running code or scripts that you didn’t write, use the Docker sandbox instead. Jobs dispatched to the sandbox run in an isolated container with a non-root user, dropped capabilities, and network controlled by the proxy. The shell tool runs directly on the host with your user’s permissions.
The injection detector operates on the command string before execution. It is not a replacement for proper shell escaping — do not rely on it as the sole guard when constructing commands from user-supplied data. The sanitizer provides defense-in-depth, not a guarantee.
Commands that exceed timeout_secs are killed. The default is 30 seconds. For long-running tasks, either increase the timeout or consider using a background job instead.