just-bash-mcp

An MCP (Model Context Protocol) server that provides a sandboxed bash environment for AI agents.

Execute bash commands in a secure, isolated environment with an in-memory virtual filesystem.

Built on top of just-bash v3.1.0.

What's New in v3.1.0

• Synced with upstream just-bash v3.1.0 - Full upstream commands, APIs, type exports, and command fixes through the latest release
• Sandbox capability forwarding - bash_sandbox_* honors Python, JavaScript, and command allow-list configuration through the new upstream SandboxOptions
• Upstream shell fixes - Includes corrected redirection routing, multiline quoted whitespace, strict-mode set -euo pipefail, heredoc substitutions, and mixed byte/text output
• Expanded command compatibility - Includes jq -R, nested jq interpolation, curl @file data, GNU tar option bundles, byte-clean head/tail, and piped-stdin rg
• Byte-safe stdin handling - Tracks the upstream v3 TypeScript-enforced stdin byte/UTF-8 model
• Executor integration plumbing - Includes upstream support for js-exec tool invocation hooks and executor package integration
• ESM runtime fix - Includes the upstream v3.0.1 dynamic require("tty")/file command crash fix
• Full upstream exec options over MCP - cwd, env, replaceEnv, stdin, stdinKind, args, rawScript, AbortSignal-backed timeoutMs, plus MCP-friendly stdinBase64
• AST transform tool - bash_transform exposes upstream BashTransformPipeline, CommandCollectorPlugin, and TeePlugin
• Persistent sandbox tools - bash_sandbox_* tools remain available for higher-level isolated workflows
• Byte-safe file IO - Persistent file tools support base64 read/write for binary content
• Defense-in-depth mode - Upstream-default monkey-patching of dangerous JS globals (set JUST_BASH_DEFENSE_IN_DEPTH=false to disable)
• Python support - Python3 via the upstream emscripten CPython runtime (JUST_BASH_ENABLE_PYTHON=true)
• MountableFS + ReadWriteFS - Real directory mounts with overlay/read-write options
• Configurable execution limits - Fine-grained control over loops, strings, arrays, heredocs, and substitutions

Features

• Sandboxed Execution: Commands run in an isolated virtual filesystem
• Stateless & Stateful Modes: Choose between isolated executions or persistent filesystem
• Network Access Control: Optional network access with URL allow-lists
• Execution Limits: Protection against infinite loops and deep recursion
• OverlayFS Support: Mount real directories as read-only with copy-on-write
• MountableFS Support: Mount multiple filesystems at different paths
• ReadWriteFS Support: Direct read-write access to real directories

Synced Upstream Features

The current wrapper release tracks just-bash v3.1.0, including:

• Sandbox forwarding for Python, JavaScript, command filters, custom commands, and custom fetch implementations
• Correct final-target routing for chained stdout/stderr redirections
• UTF-8 fixes for scripts that mix text and byte-producing statements
• Multiline quoted-string whitespace preservation
• Defense-in-depth fixes for ordinary variable assignments
• Heredoc-aware command-substitution parsing
• set -euo pipefail short-option cluster support
• jq -R raw-input mode and nested quoted strings in interpolation
• curl @file handling for data options
• GNU old-style tar option bundles such as tar czf
• Byte-clean head/tail, piped-stdin rg, and corrected JavaScript Buffer encodings
• UTC-by-default date behavior with explicit TZ support
• Breaking v3 stdin byte/UTF-8 handling updates for custom commands
• Executor and js-exec integration plumbing
• ESM Node bundle dynamic-require fix for commands that load tty transitively
• jq control-character handling inside JSON strings
• Faster grep pattern matching via matcher reuse and literal pre-filtering
• AWK lexer fixes for POSIX multi-line statement continuation
• Bug fixes across network, sqlite3, xan, rg, terminal rendering, and CI
• Workspace/Changesets migration with unchanged public import paths and bin entries
• Defense-in-depth hardening across the runtime and filesystem layers
• Defense-in-depth enabled by default upstream, plus additional hardening passes
• Filesystem hardening for overlays, external filesystems, symlinks, and broken symlink handling
• Virtualized PID and shell security invariant improvements
• Updated Sandbox.runCommand() signature compatibility
• Python runtime migration from Pyodide to emscripten CPython
• Follow-up Python runtime hardening and cleanup
• UTF-8 handling and write-path fixes
• CommonJS compatibility improvements upstream
• ls -F / --classify support
• Additional cleanup and internal hardening work shipped through v3.1.0

GitHub main audit

Checked vercel-labs/just-bash main at commit 6130334f0ed013771bbe39f32a249bdaf762c488. It is one unreleased command-only commit ahead of v3.1.0, adding GNU cat display flags (-A, -b, -e, -E, -s, -t, -T, and -v). The upstream manifest remains 3.1.0; this wrapper intentionally tracks the reproducible npm release rather than an unversioned Git commit.

Installation

From npm (recommended)

Requires Node.js 22 or newer.

npm install -g just-bash-mcp

# Or with bun
bun add -g just-bash-mcp

From source

git clone https://github.com/dalist1/just-bash-mcp.git
cd just-bash-mcp
bun install
bun run check

Usage

Running the Server

just-bash-mcp

# Or from source
bun run dev

MCP Client Configuration

Using npx (no installation required)

{
  "mcpServers": {
    "just-bash": {
      "command": "npx",
      "args": ["-y", "just-bash-mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "just-bash": {
      "command": "npx",
      "args": ["-y", "just-bash-mcp"]
    }
  }
}

Cursor / VS Code (Roo Code / Cline) / Windsurf

Add to your MCP settings:

{
  "mcpServers": {
    "just-bash": {
      "command": "npx",
      "args": ["-y", "just-bash-mcp"]
    }
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | JUST_BASH_CWD | Initial working directory | /home/user | | JUST_BASH_INITIAL_ENV | JSON object of initial env vars, e.g. {"TZ":"UTC"} | - | | JUST_BASH_OVERLAY_ROOT | Real directory to mount as copy-on-write overlay | - | | JUST_BASH_OVERLAY_READ_ONLY | OverlayFS read-only mode | false | | JUST_BASH_READ_WRITE_ROOT | Real directory with read-write access | - | | JUST_BASH_MOUNTS | JSON array of mount configurations | - | | JUST_BASH_ALLOW_NETWORK | Enable network access (true/false) | false | | JUST_BASH_ALLOWED_URLS | Comma-separated URL prefixes to allow | - | | JUST_BASH_ALLOWED_URLS_JSON | JSON array of URL strings or {url, transform:[{headers}]} entries | - | | JUST_BASH_ALLOWED_METHODS | Comma-separated HTTP methods to allow | GET,HEAD | | JUST_BASH_DENY_PRIVATE_RANGES | Reject private/loopback network ranges | upstream default (true in production, otherwise false) | | JUST_BASH_MAX_REDIRECTS | Maximum HTTP redirects | 20 | | JUST_BASH_NETWORK_TIMEOUT_MS | Network timeout in milliseconds | 30000 | | JUST_BASH_MAX_RESPONSE_SIZE | Max network response body size (bytes) | 10485760 | | JUST_BASH_MAX_OUTPUT_LENGTH | Maximum output length | 30000 | | JUST_BASH_MAX_CALL_DEPTH | Maximum function recursion depth | 100 | | JUST_BASH_MAX_COMMAND_COUNT | Maximum total commands per execution | 10000 | | JUST_BASH_MAX_LOOP_ITERATIONS | Maximum iterations per loop | 10000 | | JUST_BASH_MAX_AWK_ITERATIONS | Maximum AWK loop iterations | 10000 | | JUST_BASH_MAX_SED_ITERATIONS | Maximum sed branch iterations | 10000 | | JUST_BASH_MAX_JQ_ITERATIONS | Maximum jq loop iterations | 10000 | | JUST_BASH_MAX_JS_TIMEOUT_MS | Maximum JavaScript/js-exec timeout | 10000 | | JUST_BASH_MAX_GLOB_OPERATIONS | Maximum glob filesystem operations | 100000 | | JUST_BASH_MAX_STRING_LENGTH | Maximum string length (bytes) | 10485760 | | JUST_BASH_MAX_ARRAY_ELEMENTS | Maximum array elements | 100000 | | JUST_BASH_MAX_HEREDOC_SIZE | Maximum heredoc size (bytes) | 10485760 | | JUST_BASH_MAX_SUBSTITUTION_DEPTH | Maximum command substitution depth | 50 | | JUST_BASH_MAX_BRACE_EXPANSION_RESULTS | Maximum brace expansion results | 10000 | | JUST_BASH_MAX_EXEC_OUTPUT_SIZE | Maximum upstream stdout+stderr size (bytes) | 10485760 | | JUST_BASH_MAX_FILE_DESCRIPTORS | Maximum open file descriptors | 1024 | | JUST_BASH_MAX_SOURCE_DEPTH | Maximum source/. nesting depth | 100 | | JUST_BASH_MAX_SQLITE_TIMEOUT_MS | SQLite timeout | 5000 | | JUST_BASH_MAX_PYTHON_TIMEOUT_MS | Python timeout | 10000 | | JUST_BASH_ENABLE_PYTHON | Enable Python3 via emscripten CPython (true/false) | false | | JUST_BASH_ENABLE_JAVASCRIPT | Enable upstream js-exec via QuickJS (true/false) | false | | JUST_BASH_JAVASCRIPT_BOOTSTRAP | Bootstrap JavaScript code before each js-exec invocation | - | | JUST_BASH_DEFENSE_IN_DEPTH | Enable defense-in-depth mode (true/false) | true | | JUST_BASH_DEFENSE_IN_DEPTH_AUDIT | Audit mode: log violations but don't block | false | | JUST_BASH_DEFENSE_IN_DEPTH_LOG | Log violations to console | false | | JUST_BASH_MAX_FILE_READ_SIZE | Max file read size for OverlayFs/ReadWriteFs | 10485760 | | JUST_BASH_PROCESS_INFO | JSON object overriding virtual {pid,ppid,uid,gid} | - | | JUST_BASH_PID / JUST_BASH_PPID / JUST_BASH_UID / JUST_BASH_GID | Individual virtual process-info overrides | - | | JUST_BASH_SANDBOX_TIMEOUT_MS | Default timeout for bash_sandbox_* commands | - | | JUST_BASH_ALLOWED_COMMANDS | Comma-separated command allow-list | all | | JUST_BASH_ENABLE_LOGGING | Enable execution logging | false | | JUST_BASH_ENABLE_TRACING | Enable performance tracing | false |

Tools

bash

Execute bash commands in the sandbox environment. This is the upstream-compatible MCP exposure of the just-bash/bash-tool execute interface and accepts the same single command argument.

{
  "name": "bash",
  "arguments": {
    "command": "ls -la && cat package.json | head -5"
  }
}

bash_exec

Execute a bash command in a fresh sandboxed environment. Supports upstream exec() options: cwd, env, replaceEnv, stdin, stdinKind, args, rawScript, and timeoutMs (plus MCP-friendly stdinBase64 for byte stdin); initial files can be strings or {content, encoding, mode, mtime} objects.

{
  "name": "bash_exec",
  "arguments": {
    "command": "echo 'Hello World' && ls -la",
    "files": { "/tmp/data.json": "{\"key\": \"value\"}" }
  }
}

bash_exec_persistent

Execute a bash command in a persistent sandboxed environment. The filesystem persists across calls and supports the same upstream exec() options as bash_exec.

bash_reset

Reset the persistent bash environment, clearing all files and state.

bash_write_file / bash_read_file / bash_list_files

File operations in the persistent environment. Read/write support encoding: "utf-8" | "base64" for byte-safe content.

bash_direct_read / bash_direct_write

Direct filesystem read/write operations (bypass shell execution).

bash_info

Get information about the bash environment configuration, including defense-in-depth violation stats.

bash_get_cwd / bash_get_env

Get current working directory or environment variables.

bash_sandbox_*

Persistent isolated-environment helpers:

• bash_sandbox_run - Run a command with optional structured output/logs
• bash_sandbox_domain - Get the current sandbox domain/identifier
• bash_sandbox_write_files - Write multiple files at once
• bash_sandbox_read_file - Read a file (supports base64 encoding)
• bash_sandbox_mkdir - Create a directory
• bash_sandbox_extend_timeout - Extend the sandbox timeout budget
• bash_sandbox_stop - Stop and clean up the sandbox state
• bash_sandbox_reset - Reset the sandbox state

bash_transform

Transform a bash script with the upstream AST transform pipeline without executing it. Supports CommandCollectorPlugin and TeePlugin through collectCommands and teeOutputDir.

Supported Commands

File Operations

cat, cp, file, ln, ls, mkdir, mv, readlink, rm, split, stat, touch, tree

Text Processing

awk, base64, column, comm, cut, diff, expand, fold, grep (+ egrep, fgrep), head, join, md5sum, nl, od, paste, printf, rev, rg (ripgrep), sed, sha1sum, sha256sum, sort, strings, tac, tail, tr, unexpand, uniq, wc, xargs

Data Processing

jq (JSON), js-exec (JavaScript/TypeScript via QuickJS when enabled; node is a compatibility notice), python3/python (when enabled), sqlite3 (SQLite), xan (CSV), yq (YAML/XML/TOML/CSV)

Compression & Archives

gzip (+ gunzip, zcat), tar

Navigation & Environment

basename, cd, dirname, du, echo, env, export, find, hostname, printenv, pwd, tee, whoami

Shell Utilities

alias, bash, chmod, clear, date, expr, false, help, history, seq, sh, sleep, time, timeout, true, unalias, which

Network Commands (when enabled)

curl, html-to-markdown

Shell Features

• Pipes: cmd1 | cmd2
• Redirections: >, >>, 2>, 2>&1, <
• Command chaining: &&, ||, ;
• Variables: $VAR, ${VAR}, ${VAR:-default}
• Glob patterns: *, ?, [...], **/*.ts
• If/else, functions, loops (for, while, until)
• Symbolic and hard links

Filesystem Examples

OverlayFS (read from disk, write to memory)

{
  "env": {
    "JUST_BASH_OVERLAY_ROOT": "/path/to/your/project"
  }
}

ReadWriteFS (direct disk access)

{
  "env": {
    "JUST_BASH_READ_WRITE_ROOT": "/path/to/sandbox"
  }
}

MountableFS (multiple mounts)

{
  "env": {
    "JUST_BASH_MOUNTS": "[{\"mountPoint\":\"/data\",\"root\":\"/shared/data\",\"type\":\"overlay\"},{\"mountPoint\":\"/workspace\",\"root\":\"/tmp/work\",\"type\":\"readwrite\"}]"
  }
}

Network Access Examples

{
  "env": {
    "JUST_BASH_ALLOW_NETWORK": "true",
    "JUST_BASH_ALLOWED_URLS": "https://api.github.com,https://api.example.com"
  }
}

Credential transforms from upstream allowedUrlPrefixes are available through JUST_BASH_ALLOWED_URLS_JSON:

{
  "env": {
    "JUST_BASH_ALLOW_NETWORK": "true",
    "JUST_BASH_ALLOWED_URLS_JSON": "[{\"url\":\"https://api.example.com\",\"transform\":[{\"headers\":{\"Authorization\":\"Bearer token\"}}]}]"
  }
}

Setting JUST_BASH_ALLOW_NETWORK=true without either URL allow-list enables upstream's explicitly dangerous full-internet mode. Prefer an allow-list. Private/loopback blocking follows upstream's production default unless JUST_BASH_DENY_PRIVATE_RANGES is set explicitly.

Security Model

• Virtual filesystem isolation (no real filesystem access by default)
• Execution limits protect against infinite loops and recursion
• No host binary execution; optional WASM runtimes (Python, JS, SQLite) are controlled by feature flags
• Network disabled by default; when configured, URL and method allow-lists are enforced
• Defense-in-depth mode (enabled by default, matching upstream): Monkey-patches dangerous JS globals (Function, eval, setTimeout, process, etc.) during script execution to block escape vectors
• SecurityViolationLogger: Tracks all defense-in-depth violations with full stats accessible via bash_info
• Rich network error classification: NetworkAccessDeniedError, TooManyRedirectsError, RedirectNotAllowedError for precise error messages

Upstream API Coverage

This wrapper integrates the full public API surface of just-bash v3.1.0:

| Category | Exports Used | |----------|-------------| | Core | Bash, BashOptions, ExecOptions, BashExecResult | | Commands | CommandName, AllCommandName, getCommandNames, getNetworkCommandNames, getPythonCommandNames, getJavaScriptCommandNames | | Custom Commands | defineCommand, CustomCommand, LazyCommand | | Encoding | ByteString, decodeBytesToUtf8, encodeUtf8ToBytes, bytesOutput, textOutput, stdoutAsBytes, stdoutKind | | Filesystem | InMemoryFs, OverlayFs, ReadWriteFs, MountableFs, IFileSystem | | Network | NetworkConfig, AllowedUrlEntry, RequestTransform, SecureFetch, NetworkAccessDeniedError, TooManyRedirectsError, RedirectNotAllowedError | | Sandbox | Sandbox, SandboxCommand, SandboxOptions, OutputMessage | | Security | DefenseInDepthBox, SecurityViolationLogger, SecurityViolationError, createConsoleViolationCallback | | Transform | BashTransformPipeline, CommandCollectorPlugin, TeePlugin, serialize, transform result/types | | Trace | TraceCallback, TraceEvent |

The package root re-exports the installed upstream just-bash public API for downstream consumers, and src/types.ts remains a direct wildcard passthrough.

License

Apache-2.0