v2.8.5.3 · GPL-3.0-or-later

Bash4LLM⁺

Zero-dependency POSIX Bash client framework for secure, low-latency Large Language Model (LLM) inference, SSE streaming, persistent thread contexts, and OpenSSL AES-256 encrypted secret management.

Overview & Architecture Principles

🇮🇹 Bash4LLM⁺ è un framework client POSIX Bash progettato per eseguire operazioni con Modelli Linguistici di Grandi Dimensioni (LLM) in ambienti shell ristretti, pipeline CI/CD, container e dispositivi embedded (incluso Android Termux).

🇬🇧 Bash4LLM⁺ is a production-grade POSIX Bash client framework designed to execute Large Language Model operations in restricted shell environments, CI/CD pipelines, container instances, and embedded platforms (including Android Termux).

It achieves sub-10ms cold-start execution with zero third-party package dependencies for core CLI and TUI execution (no Python, Node.js, Docker, or pip/npm modules required), relying strictly on base system POSIX utilities, curl, and jq.

Key Capabilities

Multi-Provider Engine

Groq core provider by default, extensible to Gemini, Mistral, and Hugging Face via dynamic checksum-verified modules with Provider API contract versioning.

SSE Streaming & TUI Chat

Supports real-time Server-Sent Events (SSE) responses and features an interactive terminal UI chat REPL (extras/chat/tui-repl.sh) with multi-language i18n support.

Web GUI Interface

Optional WebApp interface (extras/gui-py/) powered by FastAPI and Vanilla ES6. Features Server-Sent Events (SSE) streaming and WCAG AAA compliant visual interface.

Encrypted Secret Vault

OpenSSL AES-256-CBC PBKDF2 encrypted vault for API keys. Memory-volatile RAM unlock context with mandatory policy enforcement (BASH4LLM_REQUIRE_VAULT=1).

Persistent Thread Sessions

Multi-turn conversation histories stored in line-delimited JSON (NDJSON) with automated SHA-256 thread ID anonymization (SAFE_THREAD_ID) and gzip rotation.

Security Invariants & Protections

  • Zero Dynamic Code Evaluation: Guarantees zero usage of shell eval, eliminating dynamic script injection vectors.
  • Zero Process Table Secret Leaking: API credentials are passed via _exec_curl_secure, which allocates an isolated temporary header file with 0600 permissions passed to cURL via -H @"$hdr_file" and unlinked immediately post-execution, preventing credential exposure in ps aux process listings.
  • Zero Shared Temp Directory Usage: Enforces private runtime execution directories created under umask 077.
  • Memory-Locked Function Guards: Critical security and network routing functions are sealed using readonly -f.
  • Ed25519 Manifest Signature Verification: Extension modules are validated against manifest.sha256 and manifest.sha256.sig using anti-TOCTOU staging copy isolation.

Runtime Requirements & System Footprint

Execution requires standard base OS utilities available in $PATH:

  • Shell Runtime: bash (version 4.0 or newer).
  • HTTP Transport & Data Processing: curl and jq.
  • POSIX Core Utilities (20): mktemp, stat, base64, find, awk, sed, grep, xargs, tr, sort, head, wc, tee, date, mv, chmod, cp, rm, printf, comm.
  • Optional Web GUI Runtime: Python ≥ 3.10 with fastapi, uvicorn, and pydantic (required strictly for --gui / --webapp execution; core CLI and TUI operate with zero external runtimes).
  • Optional Binaries (Auto-Fallback): flock (reverts to atomic mkdir locking), openssl, ssh-keygen, gzip, shred/dd.

CLI Quick Start

# Basic single-prompt query
./bash4llm "Explain quantum computing in two sentences."

# Real-time Server-Sent Events (SSE) streaming
./bash4llm --stream "Generate a POSIX shell script for sorting files."

# Launch interactive TUI REPL chat
./bash4llm --chat

# Launch Web GUI interface
./bash4llm --gui

# Execute within persistent conversation thread
./bash4llm --thread project_refactor "Analyze the auth architecture."

# Enforce Vault key retrieval policy
BASH4LLM_REQUIRE_VAULT=1 ./bash4llm "Query using encrypted vault credentials"

Canonical Exit Codes

Code Symbolic Alias Description
10 BASH4LLM_ERR_NO_API_KEY Missing, unreadable, or unauthenticated API credential.
11 BASH4LLM_ERR_BAD_MODEL Unsupported, missing, or invalid model target specification.
12 BASH4LLM_ERR_CURL_FAILED Network transport failure, timeout, or curl execution error.
13 BASH4LLM_ERR_PARSE JSON parsing error, or response syntax/SML/REGEX validation failure.
14 BASH4LLM_ERR_NO_PROMPT Missing prompt text or unreadable input source.
15 BASH4LLM_ERR_TMP File I/O error, permission error, missing core utility, or lock timeout.
16 BASH4LLM_ERR_API Upstream API error payload or non-2xx HTTP status code.
17 BASH4LLM_ERR_SEC Security policy violation, rate limit exceeded, or signature check failure.

Documentation Index

Explore full technical documentation and specifications: