BashKit

Sandboxed bash interpreter for multi-tenant environments. Written in Rust.

Features

• POSIX compliant - Substantial IEEE 1003.1-2024 Shell Command Language compliance
• Sandboxed execution - No real filesystem access by default
• Virtual filesystem - InMemoryFs, OverlayFs, MountableFs
• Resource limits - Command count, loop iterations, function depth
• Network allowlist - Control HTTP access per-domain
• Async-first - Built on tokio

Quick Start

use bashkit::Bash;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut bash = Bash::new();
    let result = bash.exec("echo hello world").await?;
    println!("{}", result.stdout); // "hello world\n"
    Ok(())
}

Built-in Commands (60+)

Shell Features

• Variables and parameter expansion ($VAR, ${VAR:-default}, ${#VAR})
• Command substitution ($(cmd))
• Arithmetic expansion ($((1 + 2)))
• Pipelines and redirections (|, >, >>, <, <<<)
• Control flow (if/elif/else, for, while, case)
• Functions (POSIX and bash-style)
• Arrays (arr=(a b c), ${arr[@]}, ${#arr[@]})
• Glob expansion (*, ?)
• Here documents (<<EOF)

Configuration

use bashkit::{Bash, ExecutionLimits, InMemoryFs};
use std::sync::Arc;

let limits = ExecutionLimits::new()
    .max_commands(1000)
    .max_loop_iterations(10000)
    .max_function_depth(100);

let mut bash = Bash::builder()
    .fs(Arc::new(InMemoryFs::new()))
    .env("HOME", "/home/user")
    .cwd("/home/user")
    .limits(limits)
    .build();

Sandbox Identity

Configure the sandbox username and hostname for whoami, hostname, id, and uname:

let mut bash = Bash::builder()
    .username("deploy")      // Sets whoami, id, and $USER env var
    .hostname("my-server")   // Sets hostname, uname -n
    .build();

// whoami → "deploy"
// hostname → "my-server"
// id → "uid=1000(deploy) gid=1000(deploy)..."
// echo $USER → "deploy"

Virtual Filesystem

use bashkit::{InMemoryFs, OverlayFs, MountableFs, FileSystem};
use std::sync::Arc;

// Layer filesystems
let base = Arc::new(InMemoryFs::new());
let overlay = Arc::new(OverlayFs::new(base));

// Mount points
let mut mountable = MountableFs::new(Arc::new(InMemoryFs::new()));
mountable.mount("/data", Arc::new(InMemoryFs::new()));

CLI Usage

# Run a script
bashkit-cli run script.sh

# Interactive REPL
bashkit-cli repl

Development

just build        # Build project
just test         # Run tests
just check        # fmt + clippy + test
just pre-pr       # Pre-PR checks

Benchmarks

BashKit includes a benchmark tool to compare performance against bash and just-bash.

just bench              # Quick benchmark run
just bench --save       # Save results with system identifier
just bench-verbose      # Detailed output
just bench-list         # List all benchmarks

Key findings:

• ~2000x faster startup - No subprocess overhead (0.004ms vs 9ms)
• ~200-1000x faster for tools - grep/sed/awk run in-process
• ~550x faster recursive functions - Fibonacci(10): 1ms vs 586ms

See crates/bashkit-bench/README.md for methodology and assumptions.

Acknowledgments

This project was inspired by just-bash from Vercel Labs. Huge kudos to the Vercel team for pioneering the idea of a sandboxed bash interpreter for AI-powered environments. Their work laid the conceptual foundation that made BashKit possible.

License

MIT