just-bash-mcp

Sandboxed bash execution for AI agents via Model Context Protocol, powered by Vercel Labs' just-bash.

Every agent in your fleet — OpenCode, Codex, Claude, Droid, Cline, Kiro, Gemini, etc. — currently runs its bash tool with full user privileges against your real filesystem. This MCP server replaces that with a sandboxed alternative: agents operate on a virtual filesystem backed by an in-memory overlay, so writes evaporate unless you explicitly commit them.

What you get

• 100+ unix commands (cat, awk, sed, jq, sqlite3, xan, yq, tar, grep, sort, find, tee, ...)

• Optional python3 (CPython compiled to WASM) and js-exec (QuickJS) — opt-in

• Pipes, redirections, variables, if/while/for, functions, all the bash you know

• A real bash, not a shell-out to PowerShell — works the same on every OS

• Path translation: /home/user/project/* ↔ your real <project-root>/*

• Network off by default; allow-list via env var

• 30s timeout, 1MB output cap, configurable

• Process kills cleanly on SIGINT/SIGTERM

Related MCP server: Kilntainers

What you don't get (intentional)

• No VM isolation. This is a TypeScript sandbox, not OS-level. It stops accidental damage — a slipped rm -rf won't kill your real project — but not a determined attacker.

• No modification of the real filesystem. The overlay is in-memory; committing is a separate step the user does explicitly.

• No PowerShell compatibility. This is bash. For your day-to-day shell on Windows, keep using PowerShell.

Install

cd "C:\tools\03-Projects\lains Tools\just-bash-mcp"
npm install
npm run build

Run standalone (for testing)

# Pipe JSON-RPC requests
$req | node dist/index.js

The server uses stdio transport. It speaks the MCP protocol.

Wire to OpenCode

Add to C:\Users\badanalysis\.config\opencode\mcp_servers.json:

"just-bash": {
  "command": "node",
  "args": ["C:\\tools\\03-Projects\\lains Tools\\just-bash-mcp\\dist\\index.js"],
  "env": {
    "JUST_BASH_PROJECT_ROOT": "C:\\path\\to\\your\\project"
  }
}

The JUST_BASH_PROJECT_ROOT should point at the project you want the agent to operate on. Each project will need its own MCP instance OR you set it to a neutral root and let the agent cd around.

Tools

bash_exec(script, timeout?)

Run a bash script in the sandbox. Returns stdout, stderr, and exit code.

// Example: agent wants to look at the project structure
await bash_exec({ script: "ls -la src/ && wc -l src/*.ts | tail -5" });

// Example: agent wants to create a new file
await bash_exec({
  script: "mkdir -p src/components && cat > src/components/Button.tsx <<'EOF\nexport function Button() { return <button>Click</button>; }\nEOF"
});
// The file lives in the overlay until committed

sandbox_status

await sandbox_status();
// {
//   project_root: "C:\\path\\to\\project",
//   age_seconds: 42,
//   executions: 7,
//   network_policy: "DISABLED" | "https://api.github.com/, ..."
// }

sandbox_reset(confirm)

Drop the in-memory overlay and start fresh. Useful when an agent has gone off-track and you want to restart from the real FS state.

await sandbox_reset({ confirm: true });

realpath(sandboxPath)

await realpath({ sandboxPath: "/home/user/project/src/index.ts" });
// "C:\\path\\to\\project\\src\\index.ts"

path_exists(sandboxPath)

await path_exists({ sandboxPath: "/home/user/project/README.md" });
// "true" | "false"

Configuration

Limits

Built into just-bash itself:

• maxCallDepth: 100 (function recursion)

• maxCommandCount: 10000 (total commands in a session)

• maxLoopIterations: 10000 (per loop)

• maxAwkIterations: 10000, maxSedIterations: 10000

Security model

License

Apache-2.0 (inherited from just-bash)

Related projects

• vercel-labs/just-bash — the underlying virtual bash

• vercel-labs/bash-tool — companion AI SDK tool

• vercel-labs/just-bash-executor — tool framework bridge (MCP, GraphQL, OpenAPI)

• Vercel Sandbox — production-grade VM with the same API