repository·main·Indexed 41 days ago
https://github.com/everruns/bashkitA high-performance, secure, in-process virtual sandbox for executing bash scripts. It provides a POSIX-compliant shell environment with a virtual filesystem, resource limits, and built-in support for LLM tool integration. Includes a C API for cross-platform deployment and a benchmarking tool, bashkit-bench, for comparing interpreter performance.
Bashkit is a virtual Bash interpreter designed for sandboxed, in-process shell execution. It is intended to be used as a runtime for scripts, an LLM tool, or a library integrated into Rust, Python, JavaScript, or TypeScript applications.
Important Security Note: Bashkit operates as a sandboxed shell runtime. It is not a normal host shell. Access to the host filesystem or network typically requires explicit opt-in and should be treated as a privileged operation.
Bashkit maintains extensive security testing suites to mitigate various attack vectors. Key testing areas include:
TM-UNI-* vulnerabilities.The bashkit-eval package produces detailed reports evaluating the performance of LLMs (like openai/gpt-5.2) on various automation tasks. Each task result includes:
[PASS] or [FAIL].dir_exists, file_contains, stdout_contains, exit_code) that must pass for the task to succeed.Common task categories include file_operations, text_processing, pipelines, scripting, data_transformation, json_processing, complex_tasks, error_recovery, system_info, archive_operations, code_search, environment, database_operations, config_management, and build_simulation.
Bashkit is organized as a Cargo workspace. Depending on your integration needs, you should target the specific crate:
crates/bashkit/: The core library containing the parser, interpreter, VFS, builtins, and the tool contract. Use this for native Rust integrations.crates/bashkit-cli/: The CLI binary for direct terminal usage.crates/bashkit-python/: Python bindings via PyO3.crates/bashkit-js/: JavaScript bindings via NAPI-RS.crates/bashkit-capi/: A versioned native C ABI for C/C++ integrations.crates/bashkit-eval/: An LLM evaluation study using the mira framework.The architecture of Bashkit is guided by four core principles:
tokio).Bash instance maintains isolated state.FileSystem and Builtin traits.Use the following official links for general information, issue tracking, and ecosystem documentation:
Bashkit includes an embedded jq JSON processor powered by jaq with a compatibility shim. It is designed to be compatible with jq versions 1.7 and 1.8. This is particularly useful for LLM agents that need to generate and execute JSON filters.
Key constraints to note:
input_filename and input_line_number are not available (they return null and 0 respectively).3. Runtime errors return exit code 5. Error messages are summarized to prevent exceeding LLM context windows.# Check the version of the embedded jq
jq --versionThe @everruns/bashkit-wasm package is a slim, single-threaded WebAssembly module designed for any JavaScript host, including browsers, edge/serverless workers (Cloudflare Workers, Vercel Edge, Deno Deploy), Node, Deno, and Bun.
Unlike the native @everruns/bashkit (napi) package, this version does not require SharedArrayBuffer or cross-origin isolation (COOP/COEP) headers, making it suitable for embedded contexts and constrained edge runtimes.
Key Features:
grep, sed, awk, find, jq, etc.).Limitations:
http_client (curl/wget) and ssh are absent. To access the network, implement a custom JS builtin that calls the host's fetch.tzdata: To keep the binary size small, the IANA database is omitted. Using a named TZ= zone (e.g., TZ=America/New_York) will cause the date command to fail with an error. Use TZ=UTC or leave it unset.import { initBashkit, Bash } from '@everruns/bashkit-wasm';
// Initialize the WASM module once
await initBashkit();
// Construct the Bash instance
const bash = new Bash();Bashkit benchmarks demonstrate significant performance advantages over standard bash across various categories. Key areas of improvement include:
grep, sed, awk, and jq.bash.Note: While most benchmarks show a Match (✓), some specific cases like large_multiline_script, large_assoc_array, str_uppercase, and str_lowercase may show mismatches (✗) or errors, indicating differences in behavior or implementation between Bashkit and standard Bash.
The bashkit-eval suite tests agent capabilities across several functional categories. Developers can use these categories to benchmark how well an LLM or agent performs specific types of shell-based tasks:
xargs for batch processing.trap for cleanup, and managing shell functions.tar.gz).GROUP BY and joins on CSV data..env files.Bashkit provides specialized builtins for common data formats to simplify script automation. These tools read from files or stdin and can be piped together.
| Builtin | Format | Best Use Case |
|---|---|---|
jq | JSON | Complex transformations, filters, and construction. |
yq | YAML / JSON | Applying jq-style expressions to YAML or safe in-place updates. |
json | JSON | Quick access (get/set/keys) without learning jq syntax. |
csv | CSV | Column selection, row filtering, and tabular data manipulation. |
tomlq | TOML | Extracting values from configuration files like Cargo.toml or pyproject.toml. |
Bashkit employs several layers of static and dynamic analysis to ensure security and memory safety.
Cargo.lock files against the RustSec Advisory Database for known CVEs.unsafe code blocks.unsafe code.