The bash tool is an Anthropic-defined client tool: Anthropic specifies the interface and trains the model on it, but your application runs the commands. You declare it by type and name only — no input_schema, because the schema is built in. When Claude wants to run a command, the response comes back with stop_reason: "tool_use"; you execute the command, return the output as a tool_result, and the loop continues.
Declaring and driving it
The current version is bash_20250124. It requires no beta header and is accepted by every model from Claude Sonnet 3.7 onward, including all current models. (A legacy bash_20241022 exists only for the retired October 2024 Sonnet 3.5 under the old computer-use beta — ignore it for new work.)
from anthropic import AnthropicBedrockMantle
client = AnthropicBedrockMantle(aws_region="us-east-1")
msg = client.messages.create(
model="anthropic.claude-opus-4-8", max_tokens=4096,
tools=[{"type": "bash_20250124", "name": "bash"}],
messages=[{"role": "user",
"content": "Run the test suite and summarize failures."}],
)
for block in msg.content:
if block.type == "tool_use" and block.name == "bash":
output = run_in_sandbox(block.input["command"]) # your code
Tool input is either {"command": "<string>"} or {"restart": true}. The API is stateless, so your application owns the persistent shell session: working directory, environment variables, and files created by one command should persist to the next, because that's what the model expects. On restart, kill the shell, start a fresh one, and confirm — a restarted session loses its working directory, environment, and running processes. Declaring the tool costs a modest, documented token overhead (325 input tokens on Opus 4.8/4.7; 244 on Opus 4.6/Sonnet 4.6 and earlier).
The security model: commands are untrusted input
Treat every command string as untrusted model output — because it is. The model can be steered by content it reads (a hostile README, a poisoned web page in context), so the official guidance is defense in depth:
- Isolate execution. Run the shell in a sandbox — a locked-down container or VM with minimal privileges, no production credentials, and restricted network egress. The blast radius of a bad command should be the sandbox, not your estate.
- Allowlist, don't blocklist. Permit a known set of executables and reject everything else. A blocklist is not sufficient: shells offer too many ways to reach the same effect.
- Bound the damage. Set timeouts and resource limits (CPU, memory, disk) on every command.
- Log everything. Record every command and its output for audit. This is also where operator permissions live: gate destructive or escalating commands behind explicit human approval in your handler — the API has no built-in permission prompt; your application is the permission system.
When a command fails, return the output with "is_error": true in the tool_result so Claude can adjust rather than repeat the mistake. The bash tool itself is eligible for Zero Data Retention on the first-party API.
Availability, and when you need something else
The bash tool is generally available on the Claude API, Claude Platform on AWS, Amazon Bedrock, and Google Vertex AI, and in beta on Microsoft Foundry — broad coverage, because execution happens on your side and platforms only need to pass the tool definition through.
Two neighbors are worth distinguishing. If you don't want to host execution at all, the code execution tool runs code server-side in Anthropic's sandboxed containers (which expose their own bash_code_execution sub-tool) — but it is not available on Bedrock or Vertex AI, so on those platforms the client-side bash tool plus your own sandbox is the path to shell-running agents. And if you need a narrower contract than "any shell command" — say, exactly three deploy operations with typed arguments — define a custom tool with its own JSON Schema (see strict tool use): a purpose-built schema is both easier to secure and easier for the model to call correctly than free-form shell.
Where to go next
The bash tool pairs naturally with the text editor tool for coding agents. Compare the server-side alternative in code execution, and see the feature matrix for platform coverage.