Skip to main content
BetaServer tools are currently in beta. The API and behavior may change.
The openrouter:bash server tool gives a model the ability to run shell commands. It mirrors Anthropic’s native bash tool and is available on the Anthropic Messages API only (/api/v1/messages). When the model needs to run a command, it calls the tool; with server-side execution enabled, OpenRouter runs the command inside an isolated, sandboxed Linux container and returns the combined output and exit code.
Messages API onlyopenrouter:bash is only available on the Anthropic Messages API. Requesting it on the Chat Completions or Responses API returns a 400 error. On those APIs, use a client-side function tool instead.

​
How It Works

  1. You include { "type": "openrouter:bash" } in your tools array on a Messages API request.
  2. Based on the user’s prompt, the model decides whether it needs to run a command and emits the call with one or more shell commands.
  3. With engine: "openrouter", OpenRouter executes the commands sequentially in a sandboxed container.
  4. The combined stdout, stderr, and exitCode are returned to the model.
  5. The model incorporates the result into its response. It may run multiple command batches in a single request if needed.
Server-side execution is opt-in: set engine: "openrouter" on the tool (see Execution engine). With the default engine (auto), the tool call is returned to your application to run client-side instead.

​
Quick Start

Send the tool on a Messages API request. Set engine: "openrouter" to run commands server-side in the OpenRouter sandbox.

​
Configuration

The bash tool accepts optional parameters to choose its execution environment: 
{
  "type": "openrouter:bash",
  "parameters": {
    "environment": { "type": "container_auto" }
  }
}
ParameterTypeDefaultDescription
environmentobjectcontainer_autoExecution environment. Use { "type": "container_auto" } for an OpenRouter-managed container, or { "type": "container_reference", "container_id": "..." } to reuse an existing container
enginestringautoWhere commands run: openrouter runs them server-side in the OpenRouter sandbox; auto/native (the default) return the tool call to your application to run client-side. See Execution engine

​
Call Arguments

The model generates the call arguments. They mirror Anthropic’s native bash tool action:
FieldTypeDescription
commandstringA single shell command to run
commandsstring[]Shell commands to run sequentially
restartbooleanReset the shell session (see Restart)
timeout_msintegerMaximum execution time for the batch
max_output_lengthintegerMaximum characters returned per stream (stdout and stderr are each capped to this)

​
Anthropic Messages API native bash tool

On the Messages API you can also use Anthropic’s native bash tool shape ({ "type": "bash_20250124", "name": "bash" }) instead of openrouter:bash. 
{
  "tools": [
    { "type": "bash_20250124", "name": "bash" }
  ]
}
The native bash_20250124 tool runs client-side by default: OpenRouter returns the tool_use to your application to execute locally, exactly as a direct call to the provider would. To run commands server-side in OpenRouter’s sandbox instead, send the OpenRouter tool shape with engine: "openrouter": 
{
  "tools": [
    {
      "type": "openrouter:bash",
      "parameters": { "engine": "openrouter" }
    }
  ]
}

​
Restart

Anthropic’s bash tool supports a restart action that resets the shell session. When the model emits { "restart": true }, OpenRouter provisions a fresh sandbox container, so commands run after a restart start from a clean state. The reset applies for the remainder of the current agentic turn. To keep a container alive across separate API requests in a conversation, send a stable session_id on each request — the sandbox is keyed by it.

​
Execution engine

The engine parameter controls where commands run:
  • openrouter — run commands server-side in the OpenRouter sandbox.
  • auto (default) / native — native passthrough: the tool call is returned to your application to run client-side, and OpenRouter does not execute the commands. The native bash_20250124 tool always uses this behavior, since it has no engine field.
This lets you opt into OpenRouter’s sandboxed execution with openrouter, while the default leaves command execution to your own application.

​
Response Format

When the model calls the bash tool, it receives a response like: 
{
  "command": "ls -la",
  "stdout": "total 0\ndrwxr-xr-x 2 root root 40 Jun  1 12:00 .\n",
  "stderr": "",
  "exitCode": 0
}
A non-zero exitCode indicates the command itself failed; the error output is returned on stderr so the model can read and react to it.

​
Security

Running shell commands is powerful and is sandboxed by design:
  • Commands execute in an isolated container — not on OpenRouter infrastructure or your machine. With container_auto the container is ephemeral; with container_reference it persists across requests.
  • Containers are scoped per account, so they are never shared across tenants.
  • Network access is intended to be disabled by default at the container level.
  • Execution time is bounded by timeout_ms (clamped to a server-side maximum).
  • stdout and stderr are each truncated to max_output_length (a per-stream cap, itself clamped to a server-side maximum).

​
Next Steps