bashkit

Features

• Secure by default - No process spawning, no filesystem access, no network access unless explicitly enabled. 280+ threats analyzed and mitigated
• POSIX compliant - Substantial IEEE 1003.1-2024 Shell Command Language compliance
• Sandboxed, in-process execution - All 167 commands reimplemented in Rust, no fork/exec
• Virtual filesystem - InMemoryFs, OverlayFs, MountableFs with optional RealFs backend (realfs feature)
• Resource limits - Command count, loop iterations, function depth, output size, filesystem size, parser fuel
• Network allowlist - HTTP access denied by default, per-domain control
• Multi-tenant isolation - Each interpreter instance is fully independent
• Custom builtins - Extend with domain-specific commands
• LLM tool contract - BashTool with discovery metadata, streaming output, and system prompts
• Script analysis - Inspect commands, arguments, and file writes before running, to drive permission prompts (guide)
• Snapshotting - Serialize shell state and VFS contents for checkpoint/resume workflows
• Scripted tool orchestration - Compose ToolDef+callback pairs into multi-tool bash scripts (bashkit-scripted-tool crate)
• Async-first - Built on tokio
• Language bindings - Python (PyO3) and JavaScript/TypeScript (NAPI-RS) for Node.js, Bun, and Deno
• Experimental: Git support - Virtual git operations on the virtual filesystem (git feature)
• Experimental: Python support - Embedded Python interpreter via Monty (python feature), or real CPython 3.14 in a WebAssembly sandbox (cpython feature)
• Experimental: TypeScript support - Embedded TypeScript interpreter via ZapCode (typescript feature)
• Experimental: SQLite support - Embedded SQLite-compatible engine via Turso (sqlite feature)

Install

cargo add bashkit

Optional features:

cargo add bashkit --features git              # Virtual git operations
cargo add bashkit --features python           # Embedded Python interpreter
cargo add bashkit --features cpython          # Real CPython 3.14 (WebAssembly sandbox)
cargo add bashkit --features typescript       # Embedded TypeScript interpreter
cargo add bashkit --features sqlite           # Embedded SQLite engine (Turso)
cargo add bashkit --features realfs           # Real filesystem backend

Tool orchestration (ScriptedTool, ToolDef, ToolRegistry) is a separate crate:

cargo add bashkit-scripted-tool

Agent Development

Install the Bashkit skill before asking a coding agent to build against the runtime:

npx skills add everruns/bashkit

Then ask your coding agent to wire Bashkit into the host project:

Using bashkit, add support for a bash tool

Enjoy :)

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(())
}

LLM Tool Contract

BashTool follows the toolkit-library contract: builder for reusable config, immutable tool metadata for discovery, and single-use executions for each call.

use bashkit::{BashTool, Tool};
use futures::StreamExt;

# #[tokio::main]
# async fn main() -> anyhow::Result<()> {
let tool = BashTool::builder()
    .username("agent")
    .hostname("sandbox")
    .build();

println!("{}", tool.description());
println!("{}", tool.system_prompt());

let execution = tool.execution(serde_json::json!({
    "commands": "printf 'hello\nworld\n'"
}))?;
let mut stream = execution.output_stream().expect("stream available");

let handle = tokio::spawn(async move { execution.execute().await });
while let Some(chunk) = stream.next().await {
    println!("{}: {}", chunk.kind, chunk.data);
}

let output = handle.await??;
assert_eq!(output.result["stdout"], "hello\nworld\n");
# Ok(())
# }

Script Analysis

analyze() reports what a script statically refers to, commands, arguments, redirect targets, functions, without running it. Hosts use it to decide whether a model-produced command needs user approval.

use bashkit::Bash;

# fn main() -> bashkit::Result<()> {
let bash = Bash::new();
let analysis = bash.analyze("cat notes.txt | grep -i todo > out.txt")?;

assert_eq!(analysis.command_names(), ["cat", "grep"]);
assert_eq!(analysis.redirects[0].path.as_deref(), Some("out.txt"));
assert!(analysis.redirects[0].mode.is_write());
assert!(!analysis.is_opaque());
# Ok(())
# }

Advisory only: names built at runtime ($cmd, $(echo rm)), eval/source, and truncated walks report as unknown and set is_opaque(), an allowlist check must consult it. Available in Rust, Node (bash.analyze()), and Python (bash.analyze()). See docs/script-analysis.md.

Overview

▶ Watch the 10-minute overview

Built-in Commands (167)

Shell Features

• Variables and parameter expansion ($VAR, ${VAR:-default}, ${#VAR}, ${var@Q}, case conversion ${var^^})
• Command substitution ($(cmd), `cmd`)
• Arithmetic expansion ($((1 + 2)), declare -i, let)
• Pipelines and redirections (|, >, >>, <, <<<, 2>&1, &>)
• Control flow (if/elif/else, for, while, until, case with ;;/;&/;;&, select)
• Functions (POSIX and bash-style) with dynamic scoping, FUNCNAME stack, caller
• Indexed arrays (arr=(a b c), ${arr[@]}, ${#arr[@]}, slicing, +=)
• Associative arrays (declare -A map=([key]=val))
• Nameref variables (declare -n)
• Brace expansion ({a,b,c}, {1..10}, {01..05})
• Glob expansion (*, ?) and extended globs (@(), ?(), *(), +(), !())
• Glob options (dotglob, nullglob, failglob, nocaseglob, globstar)
• Here documents (<<EOF, <<-EOF with tab stripping, <<< here-strings)
• Process substitution (<(cmd), >(cmd))
• Coprocesses (coproc)
• Background execution (&) with wait
• Shell options (set -euxo pipefail, shopt)
• Alias expansion
• Trap handling (trap cmd EXIT, trap cmd ERR)
• [[ ]] conditionals with regex matching (=~, BASH_REMATCH)

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();

Virtual Identity

Configure the virtual 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"

Snapshotting

Checkpoint an interpreter to bytes, then restore it later:

use bashkit::{Bash, SnapshotOptions};

# #[tokio::main]
# async fn main() -> bashkit::Result<()> {
let mut bash = Bash::new();
bash.exec("export BUILD_ID=42; echo ready > /tmp/state.txt").await?;

let snapshot = bash.snapshot()?;
let shell_only = bash.snapshot_with_options(SnapshotOptions {
    exclude_filesystem: true,
})?;
let mut restored = Bash::from_snapshot(&snapshot)?;
assert_eq!(restored.exec("echo $BUILD_ID").await?.stdout.trim(), "42");
restored.restore_snapshot(&shell_only)?;
# Ok(())
# }

See docs/snapshotting.md for Rust, Python, and Node examples, plus snapshot security notes.

Custom Builtins

Register your own commands as bash builtins. They share the interpreter's VFS and shell state, so mybuiltin > /scratch/out.json writes through and the next call sees the file.

Rust (any embedder):

use bashkit::{Bash, Builtin, BuiltinContext, BuiltinRegistry, ExecResult, async_trait};
use std::sync::Arc;

struct Greet;

#[async_trait]
impl Builtin for Greet {
    async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
        let who = ctx.args.first().map(String::as_str).unwrap_or("world");
        Ok(ExecResult::ok(format!("hello {}\n", who)))
    }
}

# #[tokio::main]
# async fn main() -> bashkit::Result<()> {
let registry = BuiltinRegistry::new();
let mut bash = Bash::builder().builtin_registry(registry.clone()).build();

// Register after construction — visible immediately, VFS untouched.
registry.insert("greet", Arc::new(Greet));
assert_eq!(bash.exec("greet Alice").await?.stdout, "hello Alice\n");
# Ok(())
# }

Registry builtins get execution-scoped VFS/request handles by default. Only trusted host code that intentionally needs a session-lived VFS handle should use registry.insert_trusted(...).

Node (@everruns/bashkit):

import { Bash } from "@everruns/bashkit";

const bash = new Bash({
  customBuiltins: {
    "get-order": (ctx) =>
      JSON.stringify({ id: ctx.argv[0], status: "shipped" }) + "\n",
  },
});

await bash.execute("mkdir -p /scratch");
await bash.execute("get-order 42 > /scratch/order.json");
console.log((await bash.execute("cat /scratch/order.json")).stdout);
// {"id":"42","status":"shipped"}

// Post-construction registration / removal too:
bash.addBuiltin("greet", (ctx) => `hello ${ctx.argv[0] ?? "world"}\n`);
bash.removeBuiltin("greet");

Resolution order: shell function → POSIX special builtin → custom builtin → baked-in builtin → $PATH, so custom builtins can override baked-ins (e.g. wrap cat with tracing) but a shell function defined in the script still wins.

See docs/custom_builtins_js.md for the full JS guide (sync vs async, BashTool, error handling, snapshot/restore behavior). Working example: examples/custom_builtins.mjs.

Experimental: Git Support

Enable the git feature for virtual git operations on the virtual filesystem. All git data lives in the VFS, no host filesystem access.

cargo add bashkit --features git

use bashkit::{Bash, GitConfig};

let mut bash = Bash::builder()
    .git(GitConfig::new()
        .author("Deploy Bot", "deploy@example.com"))
    .build();

// Local operations: init, add, commit, status, log
// Branch operations: branch, checkout, diff, reset
// Remote operations: remote add/remove, clone/push/pull/fetch (virtual mode)

See knowledge/integrations/git-support.md for the full specification.

Experimental: Python Support

Enable the python feature to embed the Monty Python interpreter (pure Rust, Python 3.12). Bashkit uses a slightly patched Monty 1.5, published as bashkit-monty and bashkit-monty-types: the patch adds a per-run memory probe and a VM checkpoint hook, so concurrent runs in one process get separate memory limits and honour cancellation. The upstream proposal is pydantic/monty#740; the forks go away once upstream has the hooks. Python code runs in-memory with configurable resource limits and VFS bridging, files created by bash are readable from Python and vice versa.

cargo add bashkit --features python

use bashkit::Bash;

let mut bash = Bash::builder().python().build();

// Inline code
bash.exec("python3 -c \"print(2 ** 10)\"").await?;

// Script files from VFS
bash.exec("python3 /tmp/script.py").await?;

// VFS bridging: open() and pathlib.Path work with the virtual filesystem
bash.exec(r#"python3 -c "
with open('/tmp/data.txt', 'w') as f:
    f.write('hello from python')
""#).await?;
bash.exec("cat /tmp/data.txt").await?; // "hello from python"

Stdlib modules: json, math, re, datetime, pathlib, os, sys, typing, csv, collections, and more. Rust embedders install bashkit::MeteredAllocator as the global allocator; it gives each run its own memory limit. Limitations: file I/O is VFS-scoped, no network, simple classes only (no inheritance), no third-party imports. See crates/bashkit/docs/python.md for the full guide.

For full CPython 3.14 (complete language and stdlib, CPython CLI semantics), enable the cpython feature and call .cpython() instead. The interpreter runs as a WebAssembly guest, one fresh instance per call. See crates/bashkit/docs/cpython.md for the trade-offs against Monty and the limitations.

Experimental: TypeScript Support

Enable the typescript feature to embed the ZapCode TypeScript interpreter (pure Rust, no V8). TypeScript code runs in-memory with configurable resource limits and VFS bridging via external function suspend/resume.

cargo add bashkit --features typescript

use bashkit::Bash;

let mut bash = Bash::builder().typescript().build();

// Inline code (ts, node, deno, bun aliases all work)
bash.exec("ts -c \"console.log(2 ** 10)\"").await?;
bash.exec("node -e \"console.log('hello')\"").await?;

// Script files from VFS
bash.exec("ts /tmp/script.ts").await?;

// VFS bridging: readFile/writeFile async functions
bash.exec(r#"ts -c "await writeFile('/tmp/data.txt', 'hello from ts')"#).await?;
bash.exec("cat /tmp/data.txt").await?; // "hello from ts"

Compat aliases (node, deno, bun) and unsupported-mode hints are configurable:

use bashkit::{Bash, TypeScriptConfig};

// Only ts/typescript, no compat aliases
let bash = Bash::builder()
    .typescript_with_config(TypeScriptConfig::default().compat_aliases(false))
    .build();

Limitations: no import/require, no eval(), no network, no process/Deno/Bun globals. See crates/bashkit/docs/typescript.md for the full guide.

Experimental: SQLite Support

Enable the sqlite feature to embed Turso, a pure-Rust, SQLite-compatible engine, backed by the bashkit virtual filesystem. Turso is BETA upstream, so the builtin is opt-in at both the cargo and runtime layer.

[dependencies]
bashkit = { version = "0.20.3", features = ["sqlite"] }

use bashkit::Bash;

let mut bash = Bash::builder()
    .sqlite()
    .env("BASHKIT_ALLOW_INPROCESS_SQLITE", "1")
    .build();

// In-memory query
bash.exec("sqlite :memory: 'SELECT 1 + 2'").await?;

// VFS-backed database — persists across invocations
bash.exec(r#"sqlite /tmp/notes.sqlite '
  CREATE TABLE IF NOT EXISTS notes(id INTEGER PRIMARY KEY, body TEXT);
  INSERT INTO notes(body) VALUES ("hello");
'"#).await?;
bash.exec("sqlite -header /tmp/notes.sqlite 'SELECT * FROM notes'").await?;

Sqlite3-shell-compatible flags (-csv, -json, -markdown, -header, -separator, -nullvalue, -cmd) and dot-commands (.tables, .schema, .dump, .read, .headers, .mode) are supported. Two IO backends are available: Memory (default, load/flush against the VFS at command boundaries) and Vfs (custom turso IO impl).

Limits via SqliteLimits cap script size, result-set rows, DB file size, wall-clock duration, and statement count. See crates/bashkit/docs/sqlite.md for the full guide.

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 script.sh

# Interactive REPL
bashkit


# Mount real filesystem (read-only or read-write)
bashkit --mount-ro /data script.sh
bashkit --mount-rw /workspace script.sh

Development

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

LLM Eval Results

Bashkit includes a mira eval study that measures how well LLMs use bashkit: one tagged 88-task dataset (bashkit_bash) covering agent tool use (58 basic, 8 multi-turn repo, 10 hard) and 12 runtime tasks (python3, sqlite3, state on the VFS), plus a 15-task one-shot script generation eval (bashkit_generate).

Latest run: 2026-10-09 (GPT-6 models added 2026-10-12), on the mira eval framework.

Repo and hard tasks carry most of the spread; the new runtime tasks (python3 and sqlite3 inside the sandbox) are near-saturated, with only Gemini and GPT-6.1 Sol missing any. See the detailed analysis.

cargo install mira-cli       # one-time: the `mira` host CLI
just eval-list               # list evals, samples, scorers, targets
just eval                    # run the bash eval across the model matrix
just eval-scripting          # run the scripting-tool eval
just eval-generate           # run the one-shot generation eval

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.

Language Bindings

C API

The experimental libbashkit native C ABI exposes opaque handles, synchronous execution, and binary-safe virtual filesystem access. See crates/bashkit-capi, including two runnable C examples.

Python

Python bindings with LangChain integration are available in crates/bashkit-python.

from bashkit import BashTool

tool = BashTool()
print(tool.description())
print(tool.help())
result = await tool.execute("echo 'Hello, World!'")
print(result.stdout)

JavaScript / TypeScript

NAPI-RS bindings for Node.js, Bun, and Deno. Available as @everruns/bashkit on npm.

import { BashTool } from '@everruns/bashkit';

const tool = new BashTool({ username: 'agent', hostname: 'sandbox' });
const result = await tool.execute("echo 'Hello, World!'");
console.log(result.stdout);

// Direct VFS access
await tool.writeFile('/tmp/data.txt', 'hello');
const content = await tool.readFile('/tmp/data.txt');

Platform matrix: macOS (x86_64, aarch64), Linux (x86_64, aarch64), Windows (x86_64), WASM. See crates/bashkit-js for details.

Browser / edge (WebAssembly)

A slim, single-threaded WebAssembly build for the browser and any other JavaScript runtime, edge/serverless workers (Cloudflare Workers, Vercel Edge, Deno Deploy), Node, Deno, and Bun. Available as @everruns/bashkit-wasm on npm. It needs no SharedArrayBuffer and no COOP/COEP headers, so it drops into any web app (including iframes) and into thread-less edge runtimes.

import { initBashkit, Bash } from "@everruns/bashkit-wasm";

await initBashkit();
const bash = new Bash();
console.log(bash.executeSync('echo "Hello, browser!" | tr a-z A-Z').stdout); // HELLO, BROWSER!

Use this when a native addon can't load (browsers, edge); for a native Node.js / Bun / Deno addon use @everruns/bashkit above. See crates/bashkit-wasm for details.

Java (community)

bashkit4j — Java 17+ binding over the libbashkit C ABI via JNA (no JNI code of its own, no Docker daemon, no host bash binary). It bundles the native libraries for Windows / Linux / macOS (x86-64 + ARM64) inside the jar and covers sandboxed execution, in-memory VFS, opt-in host-directory mounts, resource limits, wall-clock timeout, and cancellation. Published on Maven Central as io.github.terseprompts:bashkit4j (javadoc). Independent community project, unaffiliated with Everruns.

Elixir (community)

ex_bashkit — Elixir NIF binding with precompiled binaries for macOS / Linux (x86-64 + ARM64). It offers stateless execution plus persistent sessions backed by the in-memory VFS. Published on Hex as ex_bashkit. Independent community project, unaffiliated with Everruns.

.NET (community)

computerwelt — Community .NET binding for Bashkit. Independent community project, unaffiliated with Everruns.

Security

Bashkit is built for running untrusted scripts from AI agents and users. Security is a core design goal, not an afterthought.

Defense in Depth

Threat Model

280+ identified threats across 17 categories (DoS, sandbox escape, info disclosure, injection, network, isolation, internal errors, git, SSH, logging, crypto, Python, TypeScript, SQLite, Unicode, filesystem, snapshots), each with a stable ID, mitigation status, and test coverage.

See the threat model for the full analysis and security policy for reporting vulnerabilities.

Other Virtual Bash Implementations

• just-bash (TypeScript, Apache-2.0), Virtual bash interpreter for AI agents by Vercel Labs. Custom recursive descent parser, 75+ reimplemented commands (including full awk/sed/jq), in-memory VFS, defense-in-depth sandboxing, AST transform plugins. Runs in Node.js and browser.
• gbash (Go, Apache-2.0), Deterministic, sandbox-only bash runtime for AI agents. Delegates parsing to mvdan/sh. Registry-backed commands, policy enforcement, structured tracing, JSON-RPC server mode.

Acknowledgments

Bashkit is an independent implementation that draws design inspiration from several open source projects:

• just-bash (Vercel Labs, Apache-2.0), Pioneered the idea of a virtual bash interpreter for AI-powered environments. Bashkit's sandboxing architecture and multi-tenant design was inspired by their approach.
• Oils (Andy Chu, Apache-2.0), Comprehensive bash compatibility testing approach inspired our spec test methodology.
• One True AWK (Lucent Technologies), AWK language semantics reference for our awk builtin.
• jq (Stephen Dolan, MIT), jq query syntax and behavior reference. Our implementation uses the jaq Rust crates.

No code was copied from any of these projects. See NOTICE for full details.

How can I support this project?

Bashkit is a free, open-source hobby project. There are many ways to help:

• Use Bashkit and tell us about your experience on Discord or by email (mykhailo@everruns.com)
• Report bugs in GitHub Issues; a minimal script that behaves differently from real bash is the best bug report
• Star the repository, it helps other people find it
• Write a blog post or share what you built with it
• Help with the docs by asking questions or sending PRs
• Contribute code, such as a builtin or a compatibility test (see below, and say hi on Discord)
• Talk about Bashkit around you

Contributing

The best way to contribute is to open an issue, bug reports, feature requests, and questions all help improve bashkit. If you'd like to contribute code, see CONTRIBUTING.md for setup and workflow details.

Ecosystem

Bashkit is part of the Everruns ecosystem.

License

MIT