Bash

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.

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.

1
const response = await fetch('https://openrouter.ai/api/v1/messages', {
2
  method: 'POST',
3
  headers: {
4
    Authorization: 'Bearer {{API_KEY_REF}}',
5
    'Content-Type': 'application/json',
6
  },
7
  body: JSON.stringify({
8
    model: '{{MODEL}}',
9
    max_tokens: 1024,
10
    messages: [
11
      {
12
        role: 'user',
13
        content: 'List the files in the current directory and show me the OS version.'
14
      }
15
    ],
16
    tools: [
17
      { type: 'openrouter:bash', parameters: { engine: 'openrouter' } }
18
    ]
19
  }),
20
});
21
22
const data = await response.json();
23
console.log(data);

Configuration

The bash tool accepts optional parameters to choose its execution environment:

1
{
2
  "type": "openrouter:bash",
3
  "parameters": {
4
    "environment": { "type": "container_auto" }
5
  }
6
}

Call Arguments

The model generates the call arguments. They mirror Anthropic’s native bash tool action:

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.

1
{
2
  "tools": [
3
    { "type": "bash_20250124", "name": "bash" }
4
  ]
5
}

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":

1
{
2
  "tools": [
3
    {
4
      "type": "openrouter:bash",
5
      "parameters": { "engine": "openrouter" }
6
    }
7
  ]
8
}

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:

1
{
2
  "command": "ls -la",
3
  "stdout": "total 0\ndrwxr-xr-x 2 root root 40 Jun  1 12:00 .\n",
4
  "stderr": "",
5
  "exitCode": 0
6
}

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

• Server Tools Overview — Learn about server tools
• Web Fetch — Fetch content from URLs
• Tool Calling — Learn about user-defined tool calling