just-bash

just-bash v3.6.0 A TypeScript bash interpreter with in-memory filesystem. Designed for AI agents needing a secure, sandboxed environment. Custom commands: about About just-bash install Installation instructions github GitHub repository Or try any bash command: ls, cat, echo, grep, awk, jq, sed, etc. Type 'help' for a list of all built-in commands. npm install just-bash Usage: import { Bash } from "just-bash"; const bash = new Bash(); const result = await bash.exec("echo hello"); https://github.com/vercel-labs/just-bash # just-bash A virtual bash environment with an in-memory filesystem, written in TypeScript and designed for AI agents. Broad support for standard unix commands and bash syntax with optional curl, Python, JS/TS, and sqlite support. **Note**: This is beta software. Use at your own risk and please provide feedback. See [security model](#security-model). ## Quick Start ```bash npm install just-bash ``` ```typescript import { Bash } from "just-bash"; const bash = new Bash(); await bash.exec('echo "Hello" > greeting.txt'); const result = await bash.exec("cat greeting.txt"); console.log(result.stdout); // "Hello\n" console.log(result.exitCode); // 0 ``` Each `exec()` call gets its own isolated shell state — environment variables, functions, and working directory reset between calls. The **filesystem is shared** across calls, so files written in one `exec()` are visible in the next. ## Custom Commands Extend just-bash with your own TypeScript commands using `defineCommand`: ```typescript import { Bash, decodeBytesToUtf8, defineCommand } from "just-bash"; const hello = defineCommand("hello", async (args, ctx) => { const name = args[0] || "world"; return { stdout: `Hello, ${name}!\n`, stderr: "", exitCode: 0 }; }); const upper = defineCommand("upper", async (args, ctx) => { // ctx.stdin is a ByteString — decode to text before string ops. return { stdout: decodeBytesToUtf8(ctx.stdin).toUpperCase(), stderr: "", exitCode: 0, }; }); const bash = new Bash({ customCommands: [hello, upper] }); await bash.exec("hello Alice"); // "Hello, Alice!\n" await bash.exec("echo 'test' | upper"); // "TEST\n" ``` Custom command callbacks receive a `ResolvedCommandContext` with `fs`, `cwd`, `env`, `stdin`, resolved `limits`, and `exec` (for subcommands), and work with pipes, redirections, and all shell features. The legacy `CommandContext` remains available for standalone context inputs; use `createCommandContext({ fs })` when calling a command directly with a fully resolved context. Host-provided commands preserve the legacy trusted default whether supplied to the `Bash` constructor, declared through `defineCommand`, loaded lazily, or added later with `bash.registerCommand()`. Set `trusted: false` (or use `defineCommand(name, execute, { trusted: false })`) to select the restricted extension boundary. Trusted commands run in the embedding process and should never execute guest-provided JavaScript. Every invocation is bound by `maxExecutionTimeMs`. On cancellation, just-bash revokes the command context immediately; `maxExtensionCleanupTimeMs` only bounds how long it waits for the now-authority-free command promise to settle. A command that is still resolving, such as one whose module is loading, is never started and reports cancellation immediately instead. A late continuation cannot use `ctx.fs`, `ctx.env`, `ctx.exec`, or other context capabilities. Cleanup work that must run at scope closure can be registered with `ctx.executionScope.registerCleanup()`. A cleanup failure is returned as a generic exit-126 shell result rather than rejecting `Bash.exec()` or exposing host error details. JavaScript cannot forcibly stop arbitrary host code, so extensions requiring a hard guarantee against external side effects must run in a terminable worker or process. Tests that invoke command objects directly can use `createCommandContext({ fs })` to get a fully resolved context without duplicating internal defaults. <details> <summary><h2>Supported Commands</h2></summary> ### File Operations `cat`, `cp`, `file`, `ln`, `ls`, `mkdir`, `mktemp`, `mv`, `readlink`, `rm`, `rmdir`, `split`, `stat`, `touch`, `tree` ### Text Processing `awk`, `base64`, `column`, `comm`, `cut`, `diff`, `expand`, `fold`, `grep` (+ `egrep`, `fgrep`), `head`, `join`, `md5sum`, `nl`, `od`, `paste`, `printf`, `rev`, `rg`, `sed`, `sha1sum`, `sha256sum`, `sort`, `strings`, `tac`, `tail`, `tr`, `unexpand`, `uniq`, `wc`, `xargs` ### Data Processing `jq` (JSON), `sqlite3` (SQLite), `xan` (CSV), `yq` (YAML/XML/TOML/CSV) ### Optional Runtimes `js-exec` (JavaScript/TypeScript via QuickJS; requires `javascript: true`), `python3`/`python` (Python via CPython; requires `python: true`) ### Compression & Archives `gzip` (+ `gunzip`, `zcat`), `tar` ### Navigation & Environment `basename`, `cd`, `dirname`, `du`, `echo`, `env`, `export`, `find`, `hostname`, `printenv`, `pwd`, `tee` ### Shell Utilities `alias`, `bash`, `chmod`, `clear`, `date`, `expr`, `false`, `help`, `history`, `seq`, `sh`, `sleep`, `time`, `timeout`, `true`, `unalias`, `which`, `whoami`, `yes` ### Network `curl`, `html-to-markdown` (require [network configuration](#network-access)) All commands support `--help` for usage information. ### Shell Features - **Pipes**: `cmd1 | cmd2` - **Redirections**: `>`, `>>`, `2>`, `2>&1`, `<` - **Command chaining**: `&&`, `||`, `;` - **Variables**: `$VAR`, `${VAR}`, `${VAR:-default}` - **Positional parameters**: `$1`, `$2`, `$@`, `$#` - **Glob patterns**: `*`, `?`, `[...]` - **If statements**: `if COND; then CMD; elif COND; then CMD; else CMD; fi` - **Functions**: `function name { ... }` or `name() { ... }` - **Local variables**: `local VAR=value` - **Loops**: `for`, `while`, `until` - **Symbolic links**: `ln -s target link` - **Hard links**: `ln target link` </details> ## Ripgrep Compatibility `rg` supports ripgrep-style search options, including `--line-number --heading --color never`, context with `-C`, file types, globs, per-file match limits, and paths-only o