Enable shell execution
Shell execution lets the model run command-line programs: list and edit files, run scripts, call compilers or package managers, and use whatever tools are installed on the host. It’s also what runs Skills.
Start the server with --enable-shell, or with --agent to also turn on web search and Python:
mistralrs serve --enable-shell -m <model>Each request then decides whether the model can use the shell:
| API | How to turn shell on for a request |
|---|---|
| Responses | Add {"type": "shell", "environment": {"type": "container_auto"}} to tools. |
| Chat Completions | Set "enable_shell": true. OpenAI’s Chat Completions has no shell tool type, so this is a mistral.rs field. The web UI uses it. |
| Python and Rust SDKs | Enable shell when you build the model and again on each request, as in the examples. |
How commands run
Section titled “How commands run”Each shell call runs the model’s commands in one new shell process (/bin/sh -c by default, cmd /C on Windows), starting in the session’s working directory. Files written there stay available to later calls in the same session. Shell state such as variables and cd doesn’t carry over, because every call starts a new process.
Each call can run for up to --shell-timeout seconds (600 by default). The model can ask for a shorter limit on a call, but never a longer one. The model sees the first 4,096 characters of stdout and of stderr, and can ask for more on a given call.
Configuration
Section titled “Configuration”| Flag | Default | What it does |
|---|---|---|
--shell-path <path> |
/bin/sh on Unix, cmd on Windows |
The shell to run commands with, for example /bin/bash. |
--shell-timeout <secs> |
600 | How long one call may run. |
--shell-workdir <path> |
a new temp directory per session | Parent directory for session working directories. See working directory. |
--skills-dir <path> |
mistralrs-skills in the system temp directory |
Where uploaded Skills are stored. |
--agent-permission <mode> |
auto |
auto runs commands right away, ask waits for your app or user to approve, deny refuses. See permissions and approvals. |
--sandbox <mode> |
auto |
auto sandboxes commands on Linux and macOS, on also fails at startup if part of the sandbox is unavailable, off gives commands full access to the host. See the sandbox reference. |
The permission mode decides whether a command may run at all. The sandbox decides what it can touch once it starts.
Examples
Section titled “Examples”from openai import OpenAI
client = OpenAI(base_url="http://localhost:1234/v1", api_key="not-used")
response = client.responses.create( model="default", input="Use the shell to count the files in the current directory.", tools=[{"type": "shell", "environment": {"type": "container_auto"}}], extra_body={"max_tool_rounds": 4},)
print(response.output_text)from mistralrs import ChatCompletionRequest, Runner, ShellConfig, Which
runner = Runner( which=Which.Plain(model_id="Qwen/Qwen3-4B"), shell_config=ShellConfig(),)
resp = runner.send_chat_completion_request( ChatCompletionRequest( model="default", messages=[{"role": "user", "content": "Use the shell to list this directory."}], enable_shell=True, max_tool_rounds=4, ))print(resp.choices[0].message.content)use mistralrs::{ModelBuilder, RequestBuilder, ShellConfig, TextMessageRole, TextMessages};
let model = ModelBuilder::new("Qwen/Qwen3-4B") .with_shell_execution(ShellConfig::default()) .build() .await?;
let messages = TextMessages::new() .add_message(TextMessageRole::User, "Use the shell to list this directory.");let req = RequestBuilder::from(messages) .with_shell_execution() .with_max_tool_rounds(4);
let resp = model.send_chat_request(req).await?;println!("{}", resp.choices[0].message.content.as_ref().unwrap());Working directory
Section titled “Working directory”Without --shell-workdir, each session gets its own new temp directory named mistralrs-shell-<random>. mistral.rs deletes it when the session has been idle for an hour, or when your app drops the session. If the server is killed, for example with Ctrl+C, directories of live sessions are left behind.
With --shell-workdir /path, each session gets a subdirectory named after its session ID, /path/<session_id>. Reusing a session ID picks up the same directory, even after a server restart.
Input files attached to the request and any Skills it references are copied into this directory before the commands run.
File outputs
Section titled “File outputs”After each call, mistral.rs returns every file the commands created or changed in the working directory. Hidden files and dependency or cache folders (node_modules, target, tmp, cache, and similar) are skipped. A file that didn’t change isn’t returned again.
To return a file that the automatic pass skips, or to attach a format and name, the model can name it explicitly. Paths are relative to the working directory:
-
In the same call that writes the file, it adds an
outputslist next tocommands. This is part of the tool call’s JSON, not shell syntax:{"commands": ["python build_report.py --output report.html"],"outputs": [{"name": "report.html", "format": "html"}]} -
In a later round, it calls the built-in
mistralrs_surface_outputstool with the sameoutputslist. This is for files whose names it only learns after a command finishes.
Files your request lists in files are checked after every call, and a call that finds one missing reports an error entry for it.
Streaming output
Section titled “Streaming output”Over /v1/responses, shell work appears as standard OpenAI output items:
shell_call: the commands, status, and call ID.shell_call_output: stdout and stderr, exit code, whether it timed out, and status.
Over Chat Completions, the same work arrives as agentic_tool_call_progress events. See streaming a run.
Isolation
Section titled “Isolation”The CLI sandboxes commands by default; the SDKs don’t. On Linux and macOS, --sandbox auto limits commands to writing inside the session’s working directory. In the Python and Rust SDKs, ShellConfig runs commands with no sandbox unless you attach a SandboxPolicy.
The sandbox caps CPU time at 600 seconds per session by default. If --shell-timeout is longer, the cap is raised to match so long-running Skills aren’t cut off.
To run commands somewhere other than the mistral.rs host, leave shell off, define your own tool, and send its calls to a service you control with --tool-dispatch-url.
See also
Section titled “See also”- OpenAI-compatible Skills: upload and reference Skills from Responses requests.
- Permissions and approvals: gate execution behind app or user approval.
- Agentic runtime for apps: streaming events, files, and media.
- Examples: Python, Rust.