> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Shell server tool

> Run shell commands in an isolated Linux sandbox during a model response with the orq:shell server tool.

The `orq:shell` tool runs commands in an isolated Linux sandbox. One sandbox is created lazily for the response and reused for later shell calls in the same response, so files and the working directory carry across commands.

## Quick start

The examples use the client configuration from the [Server tools overview](/docs/ai-gateway/features/server-tools).

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v3/router/chat/completions \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.4-mini",
      "messages": [
        { "role": "user", "content": "Create a CSV with the first ten prime numbers, then verify the file." }
      ],
      "tools": [
        { "type": "orq:shell", "max_uses": 5, "timeout_seconds": 30 }
      ]
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await client.chat.completions.create({
    model: 'openai/gpt-5.4-mini',
    messages: [
      {
        role: 'user',
        content:
          'Create a CSV with the first ten prime numbers, then verify the file.',
      },
    ],
    tools: [{ type: 'orq:shell', max_uses: 5, timeout_seconds: 30 }] as any,
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  response = client.chat.completions.create(
      model="openai/gpt-5.4-mini",
      messages=[
          {
              "role": "user",
              "content": "Create a CSV with the first ten prime numbers, then verify the file.",
          }
      ],
      tools=[
          {"type": "orq:shell", "max_uses": 5, "timeout_seconds": 30}
      ],
  )

  print(response.choices[0].message.content)
  ```
</CodeGroup>

The model supplies the command. The tool returns separate `stdout` and `stderr` values plus the exit code. Output that exceeds the configured length ends with `[output truncated]`.

## Configuration

| Parameter           | Type    | Required | Default   | Description                                                                                |
| ------------------- | ------- | -------- | --------- | ------------------------------------------------------------------------------------------ |
| `type`              | string  | Yes      |           | Must be `orq:shell`.                                                                       |
| `max_uses`          | integer | No       | Unlimited | Maximum commands during the request. Set `0` or omit the field for no tool-specific limit. |
| `timeout_seconds`   | integer | No       | `60`      | Per-command timeout. Accepted range: 1 to 300 seconds.                                     |
| `max_output_length` | integer | No       | `16000`   | Maximum characters returned for standard output and standard error. Minimum: 1.            |

The sandbox lasts only for the current response. Cross-request containers are not supported.

## Availability and usage

The deployment must have a sandbox provider configured. This can be a cloud or on-premise sandbox provider that implements the **Orq.ai** sandbox interface.

Shell has no separate server-tool charge in this release. Each attempted command appears at `usage.server_tool_use.shell_commands`, including calls blocked by `max_uses`.