let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: rename bash tool to exec (#748) (thanks @myfunc)

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-12 02:49:55 +00:00
parent b33bd6aaeb
commit 98337a14b3
51 changed files with 294 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/gateway/background-process.md
View File

@@ -1,15 +1,15 @@
---
summary: "Background bash execution and process management"
summary: "Background exec execution and process management"
read_when:
- Adding or modifying background bash behavior
- Debugging long-running bash tasks
- Adding or modifying background exec behavior
- Debugging long-running exec tasks
---
# Background Bash + Process Tool
# Background Exec + Process Tool
Clawdbot runs shell commands through the `bash` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
Clawdbot runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
## bash tool
## exec tool
Key parameters:
- `command` (required)
@@ -24,7 +24,7 @@ Behavior:
- Foreground runs return output directly.
- When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
- Output is kept in memory until the session is polled or cleared.
- If the `process` tool is disallowed, `bash` runs synchronously and ignores `yieldMs`/`background`.
- If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
Environment overrides:
- `PI_BASH_YIELD_MS`: default yield (ms)
@@ -32,9 +32,9 @@ Environment overrides:
- `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)
Config (preferred):
- `tools.bash.backgroundMs` (default 10000)
- `tools.bash.timeoutSec` (default 1800)
- `tools.bash.cleanupMs` (default 1800000)
- `tools.exec.backgroundMs` (default 10000)
- `tools.exec.timeoutSec` (default 1800)
- `tools.exec.cleanupMs` (default 1800000)
## process tool
@@ -59,7 +59,7 @@ Notes:
Run a long task and poll later:
```json
{"tool": "bash", "command": "sleep 5 && echo done", "yieldMs": 1000}
{"tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000}
```
```json
{"tool": "process", "action": "poll", "sessionId": "<id>"}
@@ -67,7 +67,7 @@ Run a long task and poll later:
Start immediately in background:
```json
{"tool": "bash", "command": "npm run build", "background": true}
{"tool": "exec", "command": "npm run build", "background": true}
```
Send stdin:

4
docs/gateway/configuration-examples.md
View File

@@ -259,9 +259,9 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
},
tools: {
allow: ["bash", "process", "read", "write", "edit"],
allow: ["exec", "process", "read", "write", "edit"],
deny: ["browser", "canvas"],
bash: {
exec: {
backgroundMs: 10000,
timeoutSec: 1800,
cleanupMs: 1800000

19
docs/gateway/configuration.md
View File

@@ -638,7 +638,7 @@ Read-only tools + read-only workspace:
},
tools: {
allow: ["read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
deny: ["write", "edit", "bash", "process", "browser"]
deny: ["write", "edit", "exec", "process", "browser"]
}
}
]
@@ -661,7 +661,7 @@ No filesystem access (messaging/session tools enabled):
},
tools: {
allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "whatsapp", "telegram", "slack", "discord", "gateway"],
deny: ["read", "write", "edit", "bash", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
deny: ["read", "write", "edit", "exec", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
}
}
]
@@ -1274,7 +1274,7 @@ Example:
maxConcurrent: 1,
archiveAfterMinutes: 60
},
bash: {
exec: {
backgroundMs: 10000,
timeoutSec: 1800,
cleanupMs: 1800000
@@ -1427,10 +1427,11 @@ Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
Heartbeats run full agent turns. Shorter intervals burn more tokens; be mindful
of `every`, keep `HEARTBEAT.md` tiny, and/or choose a cheaper `model`.
`tools.bash` configures background bash defaults:
`tools.exec` configures background exec defaults:
- `backgroundMs`: time before auto-background (ms, default 10000)
- `timeoutSec`: auto-kill after this runtime (seconds, default 1800)
- `cleanupMs`: how long to keep finished sessions in memory (ms, default 1800000)
Legacy: `tools.bash` is still accepted as an alias.
`agents.defaults.subagents` configures sub-agent defaults:
- `maxConcurrent`: max concurrent sub-agent runs (default 1)
@@ -1447,7 +1448,7 @@ Example (disable browser/canvas everywhere):
}
```
`tools.elevated` controls elevated (host) bash access:
`tools.elevated` controls elevated (host) exec access:
- `enabled`: allow elevated mode (default true)
- `allowFrom`: per-provider allowlists (empty = disabled)
- `whatsapp`: E.164 numbers
@@ -1491,8 +1492,8 @@ Per-agent override (further restrict):
Notes:
- `tools.elevated` is the global baseline. `agents.list[].tools.elevated` can only further restrict (both must allow).
- `/elevated on|off` stores state per session key; inline directives apply to a single message.
- Elevated `bash` runs on the host and bypasses sandboxing.
- Tool policy still applies; if `bash` is denied, elevated cannot be used.
- Elevated `exec` runs on the host and bypasses sandboxing.
- Tool policy still applies; if `exec` is denied, elevated cannot be used.
`agents.defaults.maxConcurrent` sets the maximum number of embedded agent runs that can
execute in parallel across sessions. Each session is still serialized (one run
@@ -1513,7 +1514,7 @@ Defaults (if enabled):
- `"ro"`: keep the sandbox workspace at `/workspace`, and mount the agent workspace read-only at `/agent` (disables `write`/`edit`)
- `"rw"`: mount the agent workspace read/write at `/workspace`
- auto-prune: idle > 24h OR age > 7d
- tool policy: allow only `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status` (deny wins)
- tool policy: allow only `exec`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status` (deny wins)
- configure via `tools.sandbox.tools`, override per-agent via `agents.list[].tools.sandbox.tools`
- optional sandboxed browser (Chromium + CDP, noVNC observer)
- hardening knobs: `network`, `user`, `pidsLimit`, `memory`, `cpus`, `ulimits`, `seccompProfile`, `apparmorProfile`
@@ -1584,7 +1585,7 @@ Legacy: `perSession` is still supported (`true` → `scope: "session"`,
tools: {
sandbox: {
tools: {
allow: ["bash", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
allow: ["exec", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
}
}

2
docs/gateway/doctor.md
View File

@@ -111,7 +111,7 @@ Current migrations:
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.audio.transcription`
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/bash/sandbox/subagents)
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
→ `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`

2
docs/gateway/logging.md
View File

@@ -50,7 +50,7 @@ You can tune console verbosity independently via:
## Tool summary redaction
Verbose tool summaries (e.g. `🛠️ bash: ...`) can mask sensitive tokens before they hit the
Verbose tool summaries (e.g. `🛠️ exec: ...`) can mask sensitive tokens before they hit the
console stream. This is **tools-only** and does not alter file logs.
- `logging.redactSensitive`: `off` | `tools` (default: `tools`)

11
docs/gateway/sandbox-vs-tool-policy-vs-elevated.md
View File

@@ -1,6 +1,6 @@
---
title: Sandbox vs Tool Policy vs Elevated
summary: "Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated bash gates"
summary: "Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated exec gates"
read_when: "You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change."
status: active
---
@@ -11,7 +11,7 @@ Clawdbot has three related (but different) controls:
1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (Docker vs host).
2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which tools are available/allowed**.
3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is a **bash-only escape hatch** to run on the host when you’re sandboxed.
3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is an **exec-only escape hatch** to run on the host when you’re sandboxed.
## Quick debug
@@ -49,10 +49,10 @@ Rules of thumb:
- `deny` always wins.
- If `allow` is non-empty, everything else is treated as blocked.
## Elevated: bash-only “run on host”
## Elevated: exec-only “run on host”
Elevated does **not** grant extra tools; it only affects `bash`.
- If you’re sandboxed, `/elevated on` (or `bash` with `elevated: true`) runs on the host.
Elevated does **not** grant extra tools; it only affects `exec`.
- If you’re sandboxed, `/elevated on` (or `exec` with `elevated: true`) runs on the host.
- If you’re already running direct, elevated is effectively a no-op (still gated).
Gates:
@@ -74,4 +74,3 @@ Fix-it keys (pick one):
### “I thought this was main, why is it sandboxed?”
In `"non-main"` mode, group/channel keys are *not* main. Use the main session key (shown by `sandbox explain`) or switch mode to `"off"`.

6
docs/gateway/sandboxing.md
View File

@@ -17,7 +17,7 @@ This is not a perfect security boundary, but it materially limits filesystem
and process access when the model does something dumb.
## What gets sandboxed
- Tool execution (`bash`, `read`, `write`, `edit`, `process`, etc.).
- Tool execution (`exec`, `read`, `write`, `edit`, `process`, etc.).
- Optional sandboxed browser (`agents.defaults.sandbox.browser`).
- By default, the sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it.
Configure via `agents.defaults.sandbox.browser.autoStart` and `agents.defaults.sandbox.browser.autoStartTimeoutMs`.
@@ -27,7 +27,7 @@ and process access when the model does something dumb.
Not sandboxed:
- The Gateway process itself.
- Any tool explicitly allowed to run on the host (e.g. `tools.elevated`).
- **Elevated bash runs on the host and bypasses sandboxing.**
- **Elevated exec runs on the host and bypasses sandboxing.**
- If sandboxing is off, `tools.elevated` does not change execution (already on host). See [Elevated Mode](/tools/elevated).
## Modes
@@ -79,7 +79,7 @@ Docker installs and the containerized gateway live here:
Tool allow/deny policies still apply before sandbox rules. If a tool is denied
globally or per-agent, sandboxing doesn’t bring it back.
`tools.elevated` is an explicit escape hatch that runs `bash` on the host.
`tools.elevated` is an explicit escape hatch that runs `exec` on the host.
Debugging:
- Use `clawdbot sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.

8
docs/gateway/security.md
View File

@@ -184,7 +184,7 @@ Consider running your AI on a separate phone number from your personal one:
You can already build a read-only profile by combining:
- `agents.defaults.sandbox.workspaceAccess: "ro"` (or `"none"` for no workspace access)
- tool allow/deny lists that block `write`, `edit`, `bash`, `process`, etc.
- tool allow/deny lists that block `write`, `edit`, `exec`, `process`, etc.
We may add a single `readOnlyMode` flag later to simplify this configuration.
@@ -206,7 +206,7 @@ Also consider agent workspace access inside the sandbox:
- `agents.defaults.sandbox.workspaceAccess: "ro"` mounts the agent workspace read-only at `/agent` (disables `write`/`edit`)
- `agents.defaults.sandbox.workspaceAccess: "rw"` mounts the agent workspace read/write at `/workspace`
Important: `tools.elevated` is the global baseline escape hatch that runs bash on the host. Keep `tools.elevated.allowFrom` tight and don’t enable it for strangers. You can further restrict elevated per agent via `agents.list[].tools.elevated`. See [Elevated Mode](/tools/elevated).
Important: `tools.elevated` is the global baseline escape hatch that runs exec on the host. Keep `tools.elevated.allowFrom` tight and don’t enable it for strangers. You can further restrict elevated per agent via `agents.list[].tools.elevated`. See [Elevated Mode](/tools/elevated).
## Browser control risks
@@ -261,7 +261,7 @@ Common use cases:
},
tools: {
allow: ["read"],
deny: ["write", "edit", "bash", "process", "browser"]
deny: ["write", "edit", "exec", "process", "browser"]
}
}
]
@@ -285,7 +285,7 @@ Common use cases:
},
tools: {
allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "whatsapp", "telegram", "slack", "discord", "gateway"],
deny: ["read", "write", "edit", "bash", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
deny: ["read", "write", "edit", "exec", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
}
}
]