just-bash 0.1.0

A pure Python bash interpreter with in-memory virtual filesystem

just-bash-py

A pure Python bash interpreter with an in-memory virtual filesystem, designed for AI agents needing a secure, sandboxed bash environment.

This is a Python port of just-bash, the emulated bash interpreter for TypeScript, from Vercel.

Features

• Pure Python - No external binaries, no WASM dependencies
• In-memory filesystem - Sandboxed virtual filesystem for safe execution
• 70+ commands - grep, sed, awk, jq, curl, and more
• Full bash syntax - Pipes, redirections, variables, arrays, functions, control flow
• 32 shell builtins - cd, export, declare, test, and more
• Async execution - Built on asyncio for non-blocking operation
• Security limits - Prevent infinite loops, excessive recursion, runaway execution

Installation

pip install just-bash

Quick Start

import asyncio
from just_bash import Bash

async def main():
    bash = Bash()

    # Simple command
    result = await bash.exec('echo "Hello, World!"')
    print(result.stdout)  # Hello, World!

    # Pipes and text processing
    result = await bash.exec('echo "banana apple cherry" | tr " " "\\n" | sort')
    print(result.stdout)  # apple\nbanana\ncherry\n

    # Variables and arithmetic
    result = await bash.exec('x=5; echo $((x * 2))')
    print(result.stdout)  # 10

    # Arrays
    result = await bash.exec('arr=(a b c); echo "${arr[@]}"')
    print(result.stdout)  # a b c

    # In-memory files
    result = await bash.exec('echo "test" > /tmp/file.txt; cat /tmp/file.txt')
    print(result.stdout)  # test

asyncio.run(main())

Demo

Run the interactive demo to see all features in action:

python examples/demo.py

This demonstrates variables, arrays, control flow, pipes, text processing, JSON handling with jq, functions, and more.

API

Bash Class

from just_bash import Bash

# Create with optional initial files
bash = Bash(files={
    "/data/input.txt": "line1\nline2\nline3\n",
    "/config.json": '{"key": "value"}'
})

# Execute commands
result = await bash.exec("cat /data/input.txt | wc -l")

# Result object
print(result.stdout)     # Standard output
print(result.stderr)     # Standard error
print(result.exit_code)  # Exit code (0 = success)

Configuration Options

bash = Bash(
    files={...},           # Initial filesystem contents
    env={...},             # Environment variables
    cwd="/home/user",      # Working directory
    network_enabled=False, # Enable/disable network (curl)
)

Security

• No native execution - All commands are pure Python implementations
• Network disabled by default - curl requires explicit enablement
• Execution limits - Prevents infinite loops and excessive resource usage
• Filesystem isolation - Virtual filesystem keeps host system safe
• SQLite sandboxed - Only in-memory databases allowed

Supported Features

Shell Syntax

• Variables: $VAR, ${VAR}, ${VAR:-default}, ${VAR:+alt}, ${#VAR}
• Arrays: arr=(a b c), ${arr[0]}, ${arr[@]}, ${#arr[@]}
• Arithmetic: $((expr)), ((expr)), increment/decrement, ternary
• Quoting: Single quotes, double quotes, $'...', escapes
• Expansion: Brace {a,b}, tilde ~, glob *.txt, command $(cmd)
• Control flow: if/then/else/fi, for/do/done, while, until, case
• Functions: func() { ... }, local variables, return values
• Pipes: cmd1 | cmd2 | cmd3
• Redirections: >, >>, <, 2>&1, here-docs

Parameter Expansion

• Default values: ${var:-default}, ${var:=default}
• Substring: ${var:offset:length}
• Pattern removal: ${var#pattern}, ${var##pattern}, ${var%pattern}, ${var%%pattern}
• Replacement: ${var/pattern/string}, ${var//pattern/string}
• Case modification: ${var^^}, ${var,,}, ${var^}, ${var,}
• Length: ${#var}, ${#arr[@]}
• Indirection: ${!var}, ${!prefix*}, ${!arr[@]}
• Transforms: ${var@Q}, ${var@a}, ${var@A}

Conditionals

• Test command: [ -f file ], [ "$a" = "$b" ]
• Extended test: [[ $var == pattern ]], [[ $var =~ regex ]]
• Arithmetic test: (( x > 5 ))
• File tests: -e, -f, -d, -r, -w, -x, -s, -L
• String tests: -z, -n, =, !=, <, >
• Numeric tests: -eq, -ne, -lt, -le, -gt, -ge

Shell Builtins

:         .         [         alias     break     builtin   cd        command
continue  declare   eval      exec      exit      export    false     let
local     mapfile   readarray readonly  return    set       shift     shopt
source    test      true      type      typeset   unalias   unset     wait

Available Commands

File Operations

cat       chmod     cp        find      ln        ls        mkdir     mv
rm        stat      touch     tree

Text Processing

awk       column    comm      cut       diff      expand    fold      grep
egrep     fgrep     head      join      nl        od        paste     rev
rg        sed       sort      split     strings   tac       tail      tee
tr        unexpand  uniq      wc

Data Processing

jq        yq        xan       sqlite3

Path Utilities

basename  dirname   pwd       readlink  which

Compression & Encoding

base64    gzip      gunzip    zcat      md5sum    sha1sum   sha256sum tar

System & Environment

alias     clear     date      du        echo      env       expr      false
file      help      history   hostname  printenv  printf    read      seq
sleep     timeout   true      unalias   xargs

Network

curl      (disabled by default)

Shell

bash      sh

License

Apache 2.0

Acknowledgments

This project is a Python port of just-bash by Vercel. The TypeScript implementation provided the design patterns, test cases, and feature specifications that guided this Python implementation.