# Bashkit

> Bashkit runs untrusted shell scripts from AI agents without spawning a single OS process. 164 reimplemented commands, substantial POSIX shell language coverage, a virtual filesystem, resource limits, and tool interfaces for agent frameworks — all in-memory, all sandboxed.

Doc links below point at the Markdown representation of each page so it can
be fetched and read directly; links under Optional may be HTML pages or
external resources. For the full text of every guide inlined into one
document, fetch /llms-full.txt.

## Quickstarts

### Rust — The core crate

```sh
cargo add bashkit
```

```rust
use bashkit::Bash;

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

### Python — PyO3 wheel with direct Bash API

```sh
pip install bashkit
```

```python
from bashkit import Bash

bash = Bash()
result = bash.execute_sync("echo 'Hello, World!'")
print(result.stdout)

bash.execute_sync("export APP_ENV=dev")
print(bash.execute_sync("echo $APP_ENV").stdout)
```

### TypeScript — NAPI-RS runtime for Node, Bun, Deno

```sh
npm i @everruns/bashkit
```

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

const bash = new Bash();
const result = bash.executeSync('echo "Hello, World!"');
console.log(result.stdout);

bash.executeSync("X=42");
console.log(bash.executeSync("echo $X").stdout);
```

## Agent skill

- Install the skill: Give your coding agent Bashkit-specific usage notes and examples. (`npx skills add everruns/bashkit`)
- Ask agent to add it: Prompt your coding agent to wire Bashkit into the host project. (`Using bashkit, add support for a bash tool`)
- Enjoy :): Use the new bash tool in your agent workflow.
- [View skill contents](https://github.com/everruns/bashkit/tree/main/skills/bashkit): the SKILL.md and reference files the skill installs.
- [Agent Skills discovery index](https://bashkit.sh/.well-known/agent-skills/index.json): machine-readable skill manifest for coding agents.

## Common prompts

Prompts to give a coding agent that has the skill installed:

- Using bashkit, add a sandboxed bash tool to my agent.
- Embed bashkit in my Rust service to run untrusted shell scripts in-memory.
- Run this bash script in bashkit and return stdout, stderr, and the exit code.
- Add a custom builtin to bashkit that calls my internal HTTP API.

## Getting started

- [CLI](https://bashkit.sh/docs/cli.md): Run scripts with bashkit-cli: flags, exit codes, opt-in runtimes.
- [Embedding](https://bashkit.sh/docs/embedding.md): Run Bashkit as a library in Rust, Python, or TypeScript.

## LLM tools

- [LLM tools](https://bashkit.sh/docs/llm-tools.md): Expose Bashkit as a sandboxed tool for agent frameworks.
- [Scripted tool orchestration](https://bashkit.sh/docs/scripted-tools.md): Compose many tools into one bash-scriptable tool the LLM calls once.

## Concepts

- [Virtual filesystem](https://bashkit.sh/docs/filesystem.md): The in-memory VFS, its layering stack, and host-mount opt-ins.
- [Security](https://bashkit.sh/docs/security.md): Sandbox boundaries, threat model, and what scripts cannot do.

## Networking

- [Networking & HTTP](https://bashkit.sh/docs/networking.md): Default-deny HTTP, the network allowlist, and SSRF protection.
- [Credential injection](https://bashkit.sh/docs/credential-injection.md): Inject outbound HTTP credentials without exposing secrets to scripts.
- [Request signing](https://bashkit.sh/docs/request-signing.md): Transparent Ed25519 bot identity (RFC 9421) on every HTTP request.

## Runtimes

- [Python builtin](https://bashkit.sh/docs/python.md): Embedded Monty Python runtime, VFS bridging, limits, and caveats.
- [TypeScript builtin](https://bashkit.sh/docs/builtin_typescript.md): Embedded ZapCode TypeScript runtime shared with bash in-memory.
- [SQLite builtin](https://bashkit.sh/docs/sqlite.md): Embedded Turso SQLite runtime, backends, output modes, and limits.
- [SSH support](https://bashkit.sh/docs/ssh.md): Sandboxed ssh, scp, and sftp builtins with host allowlists.
- [Git](https://bashkit.sh/docs/git.md): Sandboxed git on the virtual filesystem with a configurable identity.

## Reference

- [Compatibility](https://bashkit.sh/docs/compatibility.md): Bash and builtin feature coverage, security exclusions, and known gaps.
- [jq builtin](https://bashkit.sh/docs/jq.md): Supported jq flags, filters, variables, exit codes, and compatibility notes.
- [Structured data](https://bashkit.sh/docs/structured-data.md): CSV, JSON, YAML, and TOML builtins for everyday data wrangling.

## Extending

- [Custom builtins](https://bashkit.sh/docs/custom-builtins.md): Implement Rust commands that run inside the Bashkit shell.
- [Custom builtins (JavaScript)](https://bashkit.sh/docs/custom-builtins-js.md): Register JS callbacks as persistent bash builtins from Node, Deno, or Bun.
- [Clap builtins](https://bashkit.sh/docs/clap-builtins.md): Use clap parser structs to build typed custom commands.
- [Hooks](https://bashkit.sh/docs/hooks.md): Observe, modify, or cancel execution, builtin, lifecycle, and HTTP events.
- [Live mounts](https://bashkit.sh/docs/live-mounts.md): Attach, detach, and hot-swap filesystems on a running interpreter.

## Operations

- [Snapshotting](https://bashkit.sh/docs/snapshotting.md): Serialize interpreter state and restore it for checkpoint/resume flows.
- [Logging](https://bashkit.sh/docs/logging.md): Structured tracing setup, log targets, and redaction behavior.

## Optional

- [All docs (Markdown index)](https://bashkit.sh/docs.md): grouped index of every guide.
- [Full text](https://bashkit.sh/llms-full.txt): every guide inlined into one document.
- [Builtins](https://bashkit.sh/builtins): the full sandboxed command surface.
- [Rust API](https://docs.rs/bashkit): Core crate docs, builder options, limits, and shell semantics.
- [Python](https://github.com/everruns/bashkit/blob/main/crates/bashkit-python/README.md): PyO3 package docs for direct Bash usage, snapshots, and builtins.
- [TypeScript](https://github.com/everruns/bashkit/blob/main/crates/bashkit-js/README.md): Node, Bun, and Deno runtime docs for the NAPI bindings.
- [Threat model](https://github.com/everruns/bashkit/blob/main/specs/threat-model.md): 268 documented threat cases across parser, VFS, network, and runtimes.
- [Benches history](https://bashkit.sh/benches): Interactive trends across benchmarks, criterion benches, and evals.
- [CLI reference](https://github.com/everruns/bashkit/blob/main/docs/cli.md): One-shot commands, script execution, and interactive shell usage.
- [Examples](https://github.com/everruns/bashkit/tree/main/examples): Reference programs for Rust, Python, JavaScript, and tool flows.