just-bash-mcp
Run sandboxed bash for AI agents against a virtual, in-memory overlay of a project filesystem, plus a few host-side FAF maintenance tools.
Execute bash scripts with pipes, redirections, variables, loops, functions, and 100+ Unix commands via
bash_exec.Read/search/manipulate project files safely: writes stay in the overlay and do not modify the real filesystem.
Inspect sandbox state with
sandbox_statusand reset the overlay withsandbox_reset.Translate sandbox paths to real paths with
realpathand check existence withpath_exists.Use network only when explicitly allow-listed; otherwise networking is disabled by default.
Enforce execution limits: timeout, output caps, command/loop/recursion limits.
Run FAF host-side tools on the real filesystem:
faf_migrate,faf_sync,faf_score, andfaf_moltbot_sync(some sync tools may overwrite agent docs).
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., "@just-bash-mcp Show the current git status and list the files in src/"
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.
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, ...)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 -rfwon't kill your real project — but not a determined attacker.No modification of the real filesystem from
bash_exec. The overlay is in-memory and there is no commit tool. Exception: thefaf_migrate,faf_syncandfaf_moltbot_synctools run host commands and do write real project files.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 buildTest
npm test # builds, then drives dist/index.js over MCP stdio against a temp fixtureRun standalone (for testing)
# Pipe JSON-RPC requests
$req | node dist/index.jsThe 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 committedsandbox_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
Env var | Default | Description |
|
| Project dir to mount in the overlay |
| (empty) | Comma-separated URL prefixes (e.g. |
| 30000 | Max script duration |
| 1048576 | Max stdout bytes |
| (unset) | Set to |
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
Layer | Protection |
TypeScript sandbox | Stops prototype-pollution attacks and accidental escape to host JS engine |
Filesystem isolation | Writes go to in-memory overlay; reads from real FS only at the configured project root |
Path translation |
|
Network isolation | Off by default; allow-list with URL prefix + HTTP method (GET/HEAD) |
Optional runtimes off |
|
Host FAF tools (not sandboxed) |
|
Execution limits | Prevent infinite loops, runaway computation |
No VM | If you need a full VM with arbitrary binary execution, use Vercel Sandbox instead — same API, different backend |
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
Available Tools
9 toolsbash_execA
Execute a bash script in a sandboxed virtual filesystem mounted at the project root. Writes go to an in-memory overlay and do NOT touch the real filesystem unless committed. Network is disabled unless JUST_BASH_NETWORK_ALLOW is set. Supports: cat/cp/ls/find/grep/awk/sed/sort/uniq/jq/sqlite3/xan/yq/tar/tee, optional python3 (CPython WASM) and js-exec (QuickJS) runtimes.
Inputs: script (required), timeout.
faf_migrateA
Run faf migrate on a project directory to upgrade project.faf to the latest schema version. Operates on the REAL filesystem (bypasses the bash sandbox). Modifies project.faf in place.
Inputs: project.
faf_moltbot_syncA
Run faf-moltbot sync on a project directory to generate SOUL.md with persona + constraints inline. Operates on the REAL filesystem. Overwrites SOUL.md in the project root.
Inputs: project.
faf_scoreA
Run faf score on a project directory to get a quality report (slot fill %, color). Read-only. Operates on the REAL filesystem.
Inputs: project.
faf_syncA
Run faf sync on a project directory to regenerate CLAUDE.md and other agent docs from project.faf. Operates on the REAL filesystem. May overwrite faf-generated AGENTS.md (use a custom AGENTS.md to keep your own).
Inputs: project.
path_existsA
Check if a path exists in the sandbox (overlay + real fs).
Inputs: sandboxPath (required).
realpathA
Resolve a sandbox path to its real filesystem path (for reading or committing).
Inputs: sandboxPath (required).
sandbox_resetA
Discard the current sandbox (drops all in-memory writes) and create a fresh one. Use this when you want to start over from the real project state.
Inputs: confirm (required).
sandbox_statusA
Show the current sandbox state: project root, age, exec count, last script, network policy.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools have clearly distinct purposes: bash_exec for sandboxed execution, sandbox_status/reset for sandbox lifecycle, realpath/path_exists for path resolution, and faf_* tools for different faf operations. The faf tools are differentiated by their descriptions (migrate vs sync vs score vs moltbot_sync), though the similar faf_* prefix could cause slight initial confusion.
Naming patterns are mixed: bash_exec and sandbox_reset are verb_noun, sandbox_status is noun_noun, path_exists is noun_verb, realpath is a single word, and faf_* uses a prefix plus verb. There is no uniform convention across the set, though within the sandbox and faf groups the naming is consistent.
Nine tools is well within the ideal 3-15 range and matches the server's dual-purpose scope (sandboxed bash execution and faf project management). Each tool addresses a distinct need without excessive redundancy.
The sandbox functionality is incomplete: bash_exec mentions writes go to an in-memory overlay and 'do NOT touch the real filesystem unless committed', but there is no commit tool to persist those writes. This is a critical missing operation that creates a dead end for agents trying to make changes. The faf toolset covers migrate/sync/score/moltbot_sync but lacks an init or similar setup command.
Maintenance
Related MCP Connectors
Secure Linux sandboxes for AI agents, as MCP tools.
MCP server for Superserve sandboxes: create, exec, and manage Firecracker microVMs
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Autonomous agent guardrails, bash sandboxing, MCP rugpull diffing & prompt firewalls.
Related MCP Servers
- AlicenseBqualityDmaintenanceA secure MCP server for executing whitelisted shell commands with resource and timeout controls, designed for integration with Claude and other MCP-compatible LLMs.20389 npm7MIT

Kilntainersofficial
AlicenseAqualityDmaintenanceMCP server to give every agent an ephemeral Linux sandboxes for executing shell commands.152MIT- AlicenseNot gradedqualityCmaintenanceA secure MCP server that exposes local filesystem operations to AI clients with sandboxed access and runtime directory changes.1MIT
- AlicenseAqualityDmaintenanceMCP server that gives AI assistants a secure gVisor-isolated sandbox to run Python or JavaScript code, returning stdout, stderr, and exit codes without local access.129 npmMIT