Give Any Model a Sandboxed Shell and File Workspace with OpenRouter
A practical OpenRouter beta for agent builders: let compatible models run commands in an isolated Linux container and move input or output files through the Files API.
What you get from it
What it is
OpenRouter now exposes openrouter:shell on its Responses and Messages APIs. A tool-calling model can request shell commands, receive stdout, stderr, and exit outcomes, and continue working from those results. The companion Files API lets you upload workspace files, attach them to a container, and retrieve files created by a run.
Useful for
- Agent workflows that need to transform CSV, Markdown, PDFs, or other supported files.
- Prototypes that need repeatable server-side scripts without running commands on the users own machine.
- Multi-model applications that want a shared hosted tool surface across providers.
Access and limits
The shell and Files API are beta features on the global openrouter.ai endpoint. Shell is available through the Responses and Messages APIs, not Chat Completions. Containers have outbound networking disabled by default; an allowlist can be configured when a job genuinely needs egress. Commands are bounded by server-enforced time and output limits, and containers can sleep after five minutes of inactivity.
Sandbox time is billed at $0.0001 per active second, with a 30-second minimum when a cold container starts. Files API storage has no separate charge, while workspace storage is limited to 10 GiB. Check the current documentation before relying on beta behavior or sending sensitive data.
Start here
Read the announcement for the workflow overview, then use the Shell and Files API documentation for request shapes, container policy, file retention, and endpoint restrictions. Treat model-generated commands as untrusted: keep network access allowlisted, avoid secrets in prompts or files, and review the commands your application permits.
Sources
Discussion
Share practical experience, questions, or warnings with the community.
Sign in to join the discussion and vote on comments.
Sign in