The Problem Applications that need to run user‑supplied shell scripts must isolate those scripts from the host process, the real file system, and the network. A typical approach spawns a new process, which is expensive and fragile in multi‑tenant or serverless environments. The goal here is to provide a pure‑Rust, in‑process bash interpreter that offers POSIX‑level features while guaranteeing isolation and controllable resource limits.

What This Does bashkit implements a full bash interpreter in Rust.

  • The core logic lives in crates/bashkit-coreutils-port/src/lib.rs and exposes the public API in the bashkit crate.
  • The interpreter (Bash::new) creates an InMemoryFs or OverlayFs (see vfs.rs).
  • Script execution is driven by Bash::exec → eval::eval_command in eval.rs, which parses the command line, looks up builtins (builtins.rs), and runs them without spawning subprocesses.
  • Network access is controlled via the network_allowlist in network.rs; the default is “deny all”.
  • Optional features (git, python, cpython, typescript, sqlite, realfs) add virtual Git, embedded Python, CPython WASM, TypeScript, SQLite, or a real file system backend, all wired through Cargo features.

How It Is Wired

  • Entry point: crates/bashkit-cli/src/main.rs parses CLI flags and calls Bash::new from bashkit.
  • Core path: bashkit::Bash::exec → eval::eval_command → builtins::dispatch → builtins::echo (or any other builtin).
  • Filesystem: eval::eval_command resolves paths via the Vfs trait, implemented by InMemoryFs (virtual) or MountableFs (wrapper over realfs, enabled by the realfs feature).
  • C API: crates/bashkit-capi/src/lib.rs exposes C bindings that mirror the Rust API, delegating to the same Bash implementation.
  • Bindings: The JavaScript/TypeScript and Python wrappers (napi-rs, pyo3) are thin crates that expose the same Bash struct and its methods, compiled via the corresponding Cargo features.

The main control flow involves only three function calls from the binary to the core library, keeping the blast radius minimal. There are no cycles in the main call graph; each crate has a single responsibility boundary.

How To Use It

# Add to a Rust project
cargo add bashkit
# Optional features
cargo add bashkit --features git,python
# Run the CLI
cargo run -p bashkit-cli

The CLI accepts a script file or a command string; see crates/bashkit-cli/src/main.rs for the flag parsing logic. For embedding, import the bashkit crate and construct a Bash instance:

use bashkit::Bash;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let bash = Bash::new();
    let res = bash.exec("echo hello").await?;
    println!("{}", res.stdout);
    Ok(())
}

Real‑World Use A serverless function that processes untrusted user scripts can instantiate a Bash with the realfs feature disabled, run the script, and capture the output via Bash::exec. The virtual file system guarantees that any file writes remain inside the sandbox and can be discarded after the request.

Code Health & Issues

  • Tests: 726 test files (root tests/ and per‑crate tests).
  • CI: github/workflows/ci.yml runs unit tests, linting, and docs generation.
  • License: MIT (root LICENSE).
  • Coverage: github/workflows/coverage.yml reports ≥90 % coverage.
  • Missing: No documented runtime environment variables; all configuration is compile‑time via Cargo features.
  • Security: knowledge/security/threat-model.md enumerates 280+ mitigations; the repository itself contains no process‑spawning code.

The Bottom Line bashkit delivers a secure, POSIX‑compatible bash interpreter that runs entirely in‑process. It is ideal for environments where isolation, resource limits, and deterministic execution matter. The API surface is clean, and the optional features allow incremental enrichment (Git, Python, etc.), but developers should be aware that performance is bounded by pure‑Rust execution and that certain shell features (e.g., job control) are intentionally omitted.