Skip to main content
Glama

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 -rf won'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: the faf_migrate, faf_sync and faf_moltbot_sync tools 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 build

Test

npm test   # builds, then drives dist/index.js over MCP stdio against a temp fixture

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

Env var

Default

Description

JUST_BASH_PROJECT_ROOT

cwd

Project dir to mount in the overlay

JUST_BASH_NETWORK_ALLOW

(empty)

Comma-separated URL prefixes (e.g. https://api.github.com/,https://registry.npmjs.org/)

JUST_BASH_MAX_DURATION_MS

30000

Max script duration

JUST_BASH_MAX_OUTPUT_BYTES

1048576

Max stdout bytes

JUST_BASH_ENABLE_FAF_SYNC

(unset)

Set to 1 to expose faf_sync / faf_moltbot_sync (they overwrite agent docs on the host); hidden and refused otherwise

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

realpath/path_exists reject any path whose resolved host path leaves the project root (.., .., drive letters, sibling prefixes); path_exists asks the overlay, not the host

Network isolation

Off by default; allow-list with URL prefix + HTTP method (GET/HEAD)

Optional runtimes off

python3 and js-exec are not enabled by this server

Host FAF tools (not sandboxed)

faf_* run real commands in any existing absolute directory; arguments with " % ! or newlines are refused because cmd.exe cannot pass them safely

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)

Available Tools

9 tools
bash_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

    A3.8/5.0

    Scored across 9 tools

    Disambiguation4/5

    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 Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness2/5

    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

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A secure MCP server for executing whitelisted shell commands with resource and timeout controls, designed for integration with Claude and other MCP-compatible LLMs.
      20
      389 npm
      7
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      1
      29 npm
      MIT