shell-execution-sandbox · diff
v2.0 to v2.0
3 added, 0 removed. Audit A to A.
---
name: shell-execution-sandbox
description: Enable and configure the sandboxed shell execution tool with command allowlists, Docker isolation, and audit logging for agents that run terminal commands.
compatibility: Reactive Agents TypeScript projects using @reactive-agents/*
metadata:
author: reactive-agents
version: "2.0"
tier: "capability"
---
# Shell Execution Sandbox
+ > **Disclaimer — your machine, your risk.** `shell-execute` runs real processes on the host (or in an optional Docker sandbox you configure). Allowlists and blocklists reduce accidents but are not a guarantee. Only enable for trusted codebases and accounts; review allowed command names and working-directory rules before production use. Cortex exposes this as an **explicit opt-in** in the Lab builder with the same warning.
+
## Agent objective
Produce a builder with shell execution enabled, the correct allowlist for the task, and appropriate safety config — without exposing destructive commands.
## When to load this skill
- Agent needs to run terminal commands (git, file operations, build tools)
- Agent generates and executes code (Node, Bun, Python)
- Task requires reading directory structure, running tests, or processing files
- CI/CD or automation agent workflows
## Implementation baseline
```ts
const agent = await ReactiveAgents.create()
.withProvider("anthropic")
.withReasoning({ defaultStrategy: "plan-execute-reflect", maxIterations: 15 })
.withTools({
allowedTools: ["shell-execute", "file-read", "checkpoint"],
+ terminal: true, // registers shell-execute handler (or use .withTerminalTools())
})
.withSystemPrompt(`
You have access to a shell. Use it to explore the codebase and run commands.
Always checkpoint important findings before continuing.
`)
.build();
```
## Default allowlist
The `shell-execute` tool blocks any command not on the allowlist. Default allowed commands:
```
git, ls, cat, grep, find, echo, printf
mkdir, cp, mv, touch
wc, head, tail, sort, uniq, cut, tr, tee, diff, sed, awk, jq
pwd, date, which, basename, dirname, test, true, false
seq, gzip, gunzip, zip, unzip
```
**Explicitly excluded:** `rm`, `chmod`, `chown` — too destructive for agent sandboxes.
## Key patterns
### Opt-in commands for build tasks
Build tools (Node, Bun, npm, Python, curl) are available but not on by default:
```ts
// Available opt-in commands: node, bun, npm, npx, python, python3, curl, env, xargs, tar
// Add via ShellExecuteConfig.additionalCommands when registering the tool:
import { shellExecuteTool, shellExecuteHandler } from "@reactive-agents/tools";
const shellTool = {
definition: shellExecuteTool,
handler: shellExecuteHandler({
additionalCommands: ["bun", "node", "npm"],
timeoutMs: 60_000, // default 30s — increase for build commands
maxOutputChars: 8_000, // default 4000
cwd: "/workspace", // default to project root
}),
};
const agent = await ReactiveAgents.create()
.withTools({ tools: [shellTool], allowedTools: ["shell-execute"] })
.build();
```
### Docker-isolated code execution
When `dockerEscalation` is enabled, inline code (Node `--eval`, Bun `-e`, Python `-c`) automatically routes through a Docker sandbox:
```ts
shellExecuteHandler({
additionalCommands: ["node", "python3"],
dockerEscalation: {
enabled: true,
// Inline code execution is fully isolated in a fresh container
},
})
```
### Read-only shell (safest config)
```ts
shellExecuteHandler({
allowedCommands: ["ls", "cat", "grep", "find", "head", "tail", "wc"],
// Only listing and reading — no writes, no execution
})
```
### Audit logging
```ts
shellExecuteHandler({
onAudit: (entry: ShellAuditEntry) => {
logger.info("shell-execute", {
command: entry.command,
exitCode: entry.exitCode,
durationMs: entry.durationMs,
});
},
})
```
## Shell tool properties
The `shell-execute` built-in tool has these characteristics:
| Property | Value |
|----------|-------|
| `riskLevel` | `"high"` |
| `requiresApproval` | `true` |
| `category` | `"system"` |
| `timeoutMs` (default) | 30,000ms |
| `maxOutputChars` (default) | 4,000 chars |
| `MAX_COMMAND_LENGTH` | 4,096 chars |
## Builder API reference
| Method | Key params | Notes |
|--------|-----------|-------|
| `.withTools({ tools, allowedTools })` | include `"shell-execute"` | Register custom handler for config |
| `.withTools()` | no args | Enables shell-execute but with `requiresApproval: true` |
## Pitfalls
- `shell-execute` has `requiresApproval: true` by default — in automated pipelines, register a custom handler with `requiresApproval: false` if human approval flow is not wired
- Commands are allowlisted by **executable name only** (first word) — `git` is allowed regardless of sub-command args; `curl` is opt-in
- `MAX_COMMAND_LENGTH` is 4,096 — very long piped commands will be rejected
- Docker daemon must be running for `dockerEscalation` — check before enabling in CI
- `rm`, `chmod`, `chown` are hard-excluded and cannot be added via `additionalCommands`
- `maxOutputChars: 4000` truncates long output — increase for commands that produce large output (e.g., `git log`, `find` on large trees)