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

# Server tool Shell

> Execute comandos de shell em um sandbox Linux isolado durante a resposta de um modelo com a server tool orq:shell.

A ferramenta `orq:shell` executa comandos em um sandbox Linux isolado. Um sandbox é criado sob demanda para a resposta e reutilizado nas chamadas de shell seguintes da mesma resposta; assim, os arquivos e o diretório de trabalho são mantidos entre os comandos.

## Início rápido

Os exemplos usam a configuração de cliente da [Visão geral das server tools](/docs/pt-BR/ai-gateway/features/server-tools.md).

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_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)
```

O modelo fornece o comando. Ele é executado por meio de `/bin/sh`; portanto, pipes, redirecionamentos, cadeias com `&&` e scripts de várias linhas se comportam como em um terminal. A imagem de sandbox do **Toqan Router** é Debian Linux com Python 3.13 e os coreutils padrão; um provedor de sandbox on-premise pode usar uma imagem diferente.

A ferramenta retorna `stdout`, `stderr` e um objeto `outcome`. Um comando concluído tem `outcome.type` definido como `exit`, com o `exit_code`. Uma falha do sandbox tem `outcome.type` definido como `error`, com a mensagem em um campo `error` de nível superior e sem código de saída. Uma saída que excede o tamanho configurado termina com `[output truncated]`.

## Configuração

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| - | - | - | - | - |
| `type` | string | Sim | | Deve ser `orq:shell`. |
| `max_uses` | integer | Não | Ilimitado | Máximo de comandos durante a solicitação. Defina `0` ou omita o campo para não ter limite específico da ferramenta. |
| `timeout_seconds` | integer | Não | `60` | Timeout por comando. Intervalo aceito: de 1 a 300 segundos. |
| `max_output_length` | integer | Não | `16000` | Máximo de caracteres retornados para a saída padrão e a saída de erro padrão. Mínimo: 1. |

O sandbox dura apenas a resposta atual. Containers entre solicitações não são compatíveis.

## Disponibilidade e uso

O deployment precisa ter um provedor de sandbox configurado. Pode ser um provedor de sandbox em nuvem ou on-premise que implemente a interface de sandbox do **Toqan Router**.

O Shell não tem cobrança separada como server tool nesta versão. Cada comando tentado aparece em `usage.server_tool_use.shell_commands`, incluindo chamadas bloqueadas por `max_uses`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.