Readme
BashKit
Sandboxed bash interpreter for multi-tenant environments. Written in Rust.
Features
POSIX compliant - Substantial IEEE 1003.1-2024 Shell Command Language complianceSandboxed execution - No real filesystem access by defaultVirtual filesystem - InMemoryFs, OverlayFs, MountableFsResource limits - Command count, loop iterations, function depthNetwork allowlist - Control HTTP access per-domainAsync-first - Built on tokio
Quick Start
use bashkit:: Bash;
# [ tokio ::main ] 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 (66)
Category
Commands
Core
echo printf cat read
Navigation
cd pwd ls find
Flow control
true false exit return break continue test [
Variables
export set unset local shift source
Text processing
grep sed awk jq head tail sort uniq cut tr wc
File operations
mkdir rm cp mv touch chmod rmdir
File inspection
file stat less
Archives
tar gzip gunzip
Utilities
sleep date basename dirname timeout wait
Pipeline
xargs tee
System info
whoami hostname uname id env printenv
Network
curl wget
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 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 filesystemslet base = Arc:: new( InMemoryFs:: new( ) ) ;
let overlay = Arc:: new( OverlayFs:: new( base) ) ;
// Mount pointslet 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
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.
Ecosystem
BashKit is part of the Everruns ecosystem.
License
MIT