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
bashkitcrate. - The interpreter (
Bash::new) creates anInMemoryFsorOverlayFs(see vfs.rs). - Script execution is driven by
Bash::exec→eval::eval_commandin 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_allowlistin 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.rsparses CLI flags and callsBash::newfrombashkit. - Core path:
bashkit::Bash::exec→eval::eval_command→builtins::dispatch→builtins::echo(or any other builtin). - Filesystem:
eval::eval_commandresolves paths via theVfstrait, implemented byInMemoryFs(virtual) orMountableFs(wrapper overrealfs, enabled by therealfsfeature). - C API:
crates/bashkit-capi/src/lib.rsexposes C bindings that mirror the Rust API, delegating to the sameBashimplementation. - Bindings: The JavaScript/TypeScript and Python wrappers (
napi-rs,pyo3) are thin crates that expose the sameBashstruct 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.ymlruns unit tests, linting, and docs generation. - License: MIT (root
LICENSE). - Coverage:
github/workflows/coverage.ymlreports ≥90 % coverage. - Missing: No documented runtime environment variables; all configuration is compile‑time via Cargo features.
- Security:
knowledge/security/threat-model.mdenumerates 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.