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 v2.12.5.

What's New in v2.9.5

• Synced with upstream just-bash v2.12.5 - Full upstream commands, APIs, and type exports
• Persistent sandbox tools - bash_sandbox_* tools remain available for higher-level isolated workflows
• Defense-in-depth mode - Opt-in monkey-patching of dangerous JS globals (JUST_BASH_DEFENSE_IN_DEPTH=true)
• 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 v2.12.5, which brings in the post-v2.10.2 upstream feature set, including:

• 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 v2.12.5

Installation

From npm (recommended)

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 build

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_OVERLAY_ROOT	Real directory to mount as overlay (read-only)	-
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_METHODS	Comma-separated HTTP methods to allow	GET,HEAD
JUST_BASH_MAX_REDIRECTS	Maximum HTTP redirects	20
JUST_BASH_NETWORK_TIMEOUT_MS	Network timeout in milliseconds	30000
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_ENABLE_PYTHON	Enable Python3 via emscripten CPython (true/false)	false
JUST_BASH_DEFENSE_IN_DEPTH	Enable defense-in-depth mode (true/false)	false
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_OVERLAY_READ_ONLY	OverlayFS read-only mode	false
JUST_BASH_MAX_RESPONSE_SIZE	Max network response body size (bytes)	10485760
JUST_BASH_MAX_FILE_READ_SIZE	Max file read size for OverlayFs/ReadWriteFs	10485760
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_exec

Execute a bash command in a sandboxed environment. Each execution is isolated.

{
  "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.

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.

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_stop - Stop and clean up the sandbox state
• bash_sandbox_reset - Reset the sandbox state

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), sqlite3 (SQLite), xan (CSV), yq (YAML/XML/TOML)

Compression & Archives

gzip (+ gunzip, zcat), tar

Navigation & Environment

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

Shell Utilities

alias, bash, chmod, clear, date, expr, false, help, history, seq, sh, sleep, 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"
  }
}

Security Model

• Virtual filesystem isolation (no real filesystem access by default)
• Execution limits protect against infinite loops and recursion
• No binary/WASM execution
• Network disabled by default; when enabled, URL and method allow-lists enforced
• Defense-in-depth mode (opt-in): 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 v2.12.5:

Category	Exports Used
Core	Bash, BashOptions, ExecOptions, BashExecResult
Commands	CommandName, AllCommandName, getCommandNames, getNetworkCommandNames, getPythonCommandNames
Custom Commands	defineCommand, CustomCommand, LazyCommand
Filesystem	InMemoryFs, OverlayFs, ReadWriteFs, MountableFs, IFileSystem
Network	NetworkConfig, NetworkAccessDeniedError, TooManyRedirectsError, RedirectNotAllowedError
Sandbox	Sandbox, SandboxCommand, SandboxOptions, OutputMessage
Security	DefenseInDepthBox, SecurityViolationLogger, SecurityViolationError, createConsoleViolationCallback
Trace	TraceCallback, TraceEvent

All types are re-exported from src/types.ts for downstream consumers.

License

Apache-2.0