Integrates with GitHub Copilot (VS Code) to allow it to execute shell commands within a defined sandbox, enabling agents to perform local code operations and project tasks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@shell-mcp run the test suite in the sandbox and show any failures"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for Claude Code and GitHub Copilot that runs your agent's shell commands inside a microsandbox Linux sandbox instead of on your Windows or Mac machine. Your project folder is mounted into the sandbox, so file tools keep working on the host while every command runs in Linux.
It exposes four tools: shell (foreground or background commands with a
timeout), shell_output, shell_kill and shell_list. Paths are translated
between the host folder and the sandbox mount, and the working directory is
kept across calls.
Published on npm as @edorosh/shell-mcp.
Windows (x64 or arm64) or macOS on Apple Silicon, with Node.js 22 or newer (arm64 Node on a Mac).
bash in the sandbox image (ubuntu:24.04 has it). shell-mcp creates the
sandbox itself, or attaches to one you made (see
Sandbox and runtime).
msb 0.7.11, matching the SDK that shell-mcp 1.2.0 pins. Without a separate
install, the runtime packaged with the SDK is used.
Related MCP server: Run Command MCP Server
New to microsandbox? Typical setups has ready-to-copy configurations: no internet, package registries only, full internet, extra folders, a bigger machine.
1. Check the setup, and do the first image pull in a terminal (the sandbox is created on first use and keeps running after the client exits):
npx -y @edorosh/shell-mcp@1.2.0 --sandbox myproj --image ubuntu:24.04 --mount C:\Users\<you>\dev\myproj:/workspace --preparenpx -y @edorosh/shell-mcp@1.2.0 --sandbox myproj --image ubuntu:24.04 --mount /Users/<you>/dev/myproj:/workspace --prepareAlways use the scoped name with a version. npx shell-mcp is an unrelated
package.
2. Add it to your client. Claude Code, in the project's .mcp.json:
{
"mcpServers": {
"sandbox": {
"command": "cmd",
"args": [
"/c", "npx", "-y", "@edorosh/shell-mcp@1.2.0",
"--sandbox", "myproj",
"--image", "ubuntu:24.04",
"--mount", "C:\\Users\\<you>\\dev\\myproj:/workspace"
]
}
}
}and turn off the built-in shell in .claude/settings.json:
{ "permissions": { "deny": ["Bash"] } }On a Mac, use "command": "npx" with "-y", "@edorosh/shell-mcp@1.2.0", ...
and "/Users/<you>/dev/myproj:/workspace" as the mount (see
Client setup).
For GitHub Copilot in VS Code (.vscode/mcp.json plus a hook that blocks its
built-in shell) and the Copilot CLI, see Client setup.
Ready-made files are in examples/.
3. Verify: ask the agent to run uname -a. It should report Linux.
Typical setups: ready-to-copy configurations for people new to microsandbox.
Sandbox and runtime: creating a sandbox, msb versions, upgrading.
Client setup: Claude Code, GitHub Copilot, Copilot CLI, client timeouts.
Configuration: all flags and environment variables, --check, global install.
npm ci
npm test
npm run buildSee Development for the integration suite against a real sandbox and platform pitfalls, releasing.md for releases, and the product spec for the requirements. Coding agents read AGENTS.md.
Run a shell command (bash) inside an isolated Linux sandbox, not on the host machine. The host directory /app is mounted in the sandbox at /workspace; the command starts in /workspace and only files under that directory are shared with the host. The working directory persists between calls, but environment variables and shell state (aliases, functions) do not. Do not rely on cd across parallel calls: each starts in the directory current when it starts, and the last to finish sets it. Default timeout is 120 seconds, maximum 600 seconds (timeout_ms). Use run_in_background for servers and other long-running processes; it returns a job id to use with shell_output, shell_kill and shell_list. Interactive programs (editors, pagers, prompts waiting for input) are not supported. Paths in output under /workspace are shown as host paths under /app. To read or edit files, use your file tools with host paths (/app) rather than shell commands.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The shell command to run | |
| timeout_ms | No | Timeout in milliseconds | |
| description | No | Short description of what the command does | |
| run_in_background | No | Run as a background job and return a job id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so richly: sandbox isolation, /app↔/workspace mount mapping, cwd persistence across calls, non-persistence of env vars/aliases/functions, the parallel-cd race caveat, timeout defaults and ceiling, and background job id semantics. This is exactly the behavioral context an agent needs before invoking a shell.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the single most important fact (sandbox, not host), then proceeds through mount, state, concurrency, timeout, background, and alternatives in a logical order. It runs long, but nearly every sentence carries operational meaning; only the host-path rendering note is slightly redundant with the file-tools instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a shell tool with no annotations and no output schema, the description covers isolation model, filesystem mapping, state persistence rules, concurrency hazards, timeouts, background execution, and interactive limitations. Nothing an agent needs to invoke it correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3; the description still adds value by giving the concrete default (120s) and maximum (600s) for timeout_ms and by explaining that run_in_background returns a job id consumed by shell_output/shell_kill/shell_list. Minor gap: the stated 600-second maximum conflicts with the schema's numeric maximum of 9007199254740991, which could confuse the agent on the true bound.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (run) and resource (bash shell command) with the critical scope qualifier 'inside an isolated Linux sandbox, not on the host machine'. It also implicitly distinguishes itself from the shell_output/shell_kill/shell_list siblings by naming them in the background-job workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: use run_in_background for servers/long-running processes, do not use shell for reading or editing files (use file tools with /app host paths), and interactive programs are unsupported. These are concrete use/do-not-use rules with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a background job started with shell and report whether it has stopped.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job id returned by shell |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that the call reports whether the job has stopped (implying the stop may not be instant), but it omits whether the kill is forceful, whether it is idempotent, and what happens for an unknown or already-finished job_id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the verb and resource, with no filler. Every clause (stop, report status) carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description only loosely characterizes the return as a stopped/not-stopped report. For a mutation tool with zero annotations, the absence of any note on side effects, permissions, or failure modes leaves it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single job_id parameter is documented as 'Job id returned by shell'. The description reinforces the provenance but adds no new syntax or format detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (stop) plus resource (background job started with shell), and it names the originating sibling. It doesn't contrast against shell_output or shell_list directly, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'started with shell' implies the precondition of having a job_id from a prior shell call, but there is no explicit when-to-use versus shell_list or shell_output, and no guidance for jobs that already exited or were never backgrounded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List background jobs started in this session, with their state and command.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden; it does disclose scope (session-bound) and returned content (state and command). It leaves out whether completed jobs are included, whether results are truncated or ordered, and whether the listing exposes the identifiers needed by shell_output/shell_kill.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no waste, front-loading the action and scope before the returned fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Zero parameters and no output schema means the description must characterize the result set, and it only partially does so ('state and command'). For a listing tool that feeds shell_output and shell_kill, the absence of any mention of job identifiers or result shape is a meaningful gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies; the description correctly adds the implicit filter (this session) that explains why no arguments are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('List background jobs') with an explicit scope ('started in this session') and a hint at payload ('state and command'). It is clearly distinct from shell/shell_kill, but it never names the sibling it complements (shell_output), so the differentiation is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent is expected to infer it should call this to discover jobs before using shell_output or shell_kill. There is no explicit when-to-use, when-not-to-use, or alternative routing statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read new output from a background job started with shell, since the last call. Reports whether the job is still running and its exit code once finished.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job id returned by shell |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It usefully discloses incremental reads and that it reports running status plus exit code once finished, but it leaves out details like blocking behavior, output limits, error handling, and return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no waste. The incremental-read constraint and return information are front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with no output schema, the description adequately explains what is returned in behavioral terms: new output, running status, and exit code. Minor gaps around output limits and error cases remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one required parameter with 100% schema coverage, and the schema already explains that job_id is the id returned by shell. The description does not add meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: read new output from a background job started with shell, incrementally since the last call. It also distinguishes itself from the sibling shell tools by tying the job to shell-started background work and naming its status/exit-code reporting behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly implies usage after starting a background job with shell and clarifies that reads are incremental. It does not explicitly mention alternatives such as shell_list for discovery or shell_kill for termination, but the context is sufficiently clear for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.0shellshell_killshell_listshell_outputScored across 4 tools
The four tools have clearly distinct roles: `shell` starts commands and jobs, while `shell_output`, `shell_kill`, and `shell_list` operate specifically on background jobs. There is minimal risk of confusing foreground command execution with background job management.
All tools share the `shell` prefix, and background job operations follow a consistent `shell_<operation>` pattern. The main `shell` tool is the only slight deviation, but it is still readable and predictable.
Four tools is well scoped for a sandboxed shell server: one execution tool plus three focused background-job controls. Each tool earns its place without redundant surface area.
The tool set covers foreground execution, background job launch, output streaming, termination, and listing. Given the stated non-support for interactive programs, no obvious lifecycle gaps remain.
Linux microVM sandboxes for AI agents: run commands, files, processes, pause and wake.
Manage Sprites: sandboxed compute environments with exec, services, and checkpoints.
Cloud Linux VMs for your agent: run code, Docker, files and HTTPS previews in a Sandboxer microVM.
I run shell commands on your private cloud environment (bash, sh, zsh)
