Building agents that need to run code usually means managing your own sandbox infrastructure. OpenRouter’s new shell server tool and Files API move that compute to the server side, so any model that supports tool calling can execute commands in a hosted Linux container. The feature is in beta as of September 8, 2026, and it changes where you put the execution layer in your agent stack.
How the shell tool works
You send openrouter:shell in the tools array of a request to any model with tool calling. The model decides when to invoke the terminal. When it does, OpenRouter runs the commands in an isolated container and returns stdout, stderr, and an exit code back to the model. That feedback loop lets the model react to failures—if a script hits an error, it can see the problem and fix it before answering.
curl https://openrouter.ai/api/v1/responses \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek/deepseek-v4-pro-0813",
"input": "Check the Python version, then write a script that prints the first 20 primes and run it.",
"tools": [
{ "type": "openrouter:shell", "parameters": { "engine": "openrouter" } }
]
}'There are two compatible tools: openrouter:shell follows the OpenAI spec, and openrouter:bash follows Anthropic’s. The key difference is default execution location—the bash tool normally asks your app to run commands locally, but setting engine: "openrouter" on either tool forces server-side execution.
Containers and files: the persistence layer
Containers are isolated Linux environments scoped to your workspace. Outbound network access is off by default; you can allowlist specific domains like pypi.org for package installs. Files written under /workspace/home persist between requests that share a container ID, and each shell result returns IDs for files the command created or changed.
The Files API handles moving data in and out. Upload a CSV with POST /api/v1/files, then attach it by ID in the tool’s environment. Attached files appear in the container’s home directory as writable copies, so changes inside the container don’t affect the original. To keep a generated file long-term, promote it from the container to workspace storage—promoted files are downloadable through the Files API, unlike direct uploads.
Combining shell with other server tools
Shell works alongside OpenRouter’s other server tools, like web search. A model can search the web, then use shell to write results into a markdown file. This combination matters when you want to keep the container offline: web search runs outside the container, so the model can pull in web content and pass it into commands while the container stays on the default network policy with no internet access.
This pattern echoes the shift toward agentic infrastructure where the platform handles execution details, letting you focus on the agent’s logic rather than the plumbing.
Pricing and operational notes
Sandbox time costs $0.0001 per active second, billed as part of the request. A cold container start bills a minimum of 30 seconds, but only the first request in a sequence pays that minimum. Files API usage has no separate charge, with total storage limited to 10 GiB. Containers sleep after 5 minutes idle, and container files are kept for 30 days unless promoted.
Workspace admins can disable server tools from the Server Tools page, which applies to all requests from that workspace. The API may change during beta, so treat it as a moving target for production use.
Sources
AI-assisted summary compiled from the sources above, reviewed by a human before publishing.