Skip to main content
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.
The model supplies the command. It runs through /bin/sh, so pipes, redirects, && chains, and multi-line scripts behave as they would in a terminal. The Orq.ai sandbox image is Debian Linux with Python 3.13 and the standard coreutils; an on-premise sandbox provider may run a different image. The tool returns stdout, stderr, and an outcome object. A completed command has outcome.type set to exit with the exit_code. A sandbox failure has outcome.type set to error with the message in a top-level error field and no exit code. Output that exceeds the configured length ends with [output truncated].

Configuration

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.