01
Overview
OpenRouter's hosted Shell tool lets a tool-calling model run commands in a Linux container through the same OpenRouter request that produces the model response. The beta is useful when an agent needs to execute code, inspect a file, generate an artifact or validate its own work.
02
1. Add the Shell tool
Choose a model that supports tool calling. In a Responses API request, include a tool with type openrouter:shell and set its engine to openrouter. That engine value is important: it explicitly tells OpenRouter to execute commands in its hosted sandbox. The model decides when to invoke the tool. A shell result returns command output, errors and exit status, giving the model enough information to retry or repair a failed step.
03
2. Decide whether the container needs network access
OpenRouter containers begin with outbound networking disabled. Keep that default when the job only needs local computation. If the agent must install a package or call a remote service, supply an allowlist when the container is created. For example, a Python job that needs PyPI may allow pypi.org and files.pythonhosted.org. Avoid wildcard egress unless the workload genuinely requires it. OpenRouter says the policy cannot be changed after the container starts.
04
3. Upload an input file
Upload an input with POST /api/v1/files. OpenRouter returns a workspace file ID beginning with or_file_. Add that ID to the shell environment's file list when you start the container. The attached file appears inside the container as a writable copy. Editing it in the container does not alter the original workspace upload.
05
4. Let the model process the file
Once attached, the model can use shell commands or write a script to inspect and transform the file. A CSV workflow could ask the model to identify columns, write Python to clean the data, execute the script and save a summary or chart. This is where Shell is more useful than plain text generation: the model can verify that its script actually ran and react to stderr when it did not.
06
5. Retrieve the output
Shell results include IDs for files created or modified during execution. Those container-file IDs can be downloaded through the container file-content endpoint. If an output should survive beyond the container's normal retention window, promote it into workspace storage and reuse the returned or_file_ ID later.
07
6. Reuse a container for multi-step work
OpenRouter can reuse a container when requests share a session ID or carry forward a previous shell result. You can also explicitly reference a known container. Reuse preserves useful state and can avoid repeatedly starting cold containers. That also affects cost: a cold container has a 30-second minimum sandbox charge, while successive requests against the same active container do not each pay the minimum.
08
Practical pattern: research to artifact
One useful agent workflow is to combine OpenRouter's web-search server tool with Shell. Let web search retrieve current sources, pass the material to the model, then use Shell to structure the data or write a report file. Because web search runs outside the container, the container itself can remain without direct internet access.
09
Safety and reliability checklist
Keep network egress restricted. Do not put secrets in shell prompts unless the architecture requires them and your security review permits it. Validate generated commands before giving an agent access to sensitive files or external systems. Treat tool output as untrusted input when it came from external data. Log execution results and costs. And remember that Shell is still a beta API.
10
Source
OpenRouter's September 8, 2026 launch announcement and its current Shell, Containers and Files API documentation.
Sources
Primary and supporting sources
Facts were rechecked against the linked sources immediately before publication. Pricing, product availability and rollout status can change.