Skip to content

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:

Terminal window
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.

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.

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.

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)

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.

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 outputs list next to commands. 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_outputs tool with the same outputs list. 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.

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.

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.