@mylocalgpt/shell

Virtual bash interpreter for AI agents. Pure TypeScript, zero runtime dependencies. Runs in any JavaScript runtime - browsers, Node.js, Deno, Bun, and Cloudflare Workers. Ships with 65+ commands, a full jq implementation, and an under 40KB gzipped entry point.

• Pure JS, under 40KB gzipped, zero dependencies, runs anywhere
• 65+ commands including grep, sed, awk, find, xargs, curl, and a full jq implementation
• Pipes, redirections, variables, control flow, functions, arithmetic
• Configurable execution limits, regex guardrails, no eval
• OverlayFs: read-through overlay on real directories with change tracking

Install

npm install @mylocalgpt/shell

Quick Start

import { Shell } from '@mylocalgpt/shell';

const shell = new Shell({
  files: { '/data.json': '{"name": "alice"}' },
});

const result = await shell.exec('cat /data.json | jq .name');
console.log(result.stdout); // "alice"\n

API Reference

Shell Constructor

const shell = new Shell(options?: ShellOptions);

Option	Type	Description
fs	FileSystem	Custom filesystem implementation. When provided, files is ignored.
files	Record<string, string | (() => string | Promise<string>)>	Initial filesystem contents. Values can be strings or lazy-loaded functions. Ignored when fs is provided.
env	Record<string, string>	Environment variables. Merged with defaults (HOME, USER, PATH, SHELL).
limits	Partial<ExecutionLimits>	Execution limits. Merged with safe defaults.
commands	Record<string, CommandHandler>	Custom commands to register.
onUnknownCommand	(name, args, ctx) => CommandResult	Handler for unregistered commands.
onOutput	(result) => ExecResult	Post-processing hook for exec results.
hostname	string	Virtual hostname (used by hostname command).
username	string	Virtual username (used by whoami command).
enabledCommands	string[]	Restrict available commands to this allowlist.
network	NetworkConfig	Network handler for curl. See Network Config.
onBeforeCommand	(cmd, args) => boolean | void	Hook before each command (return false to block).
onCommandResult	(cmd, result) => CommandResult	Hook after each command (can modify result).

shell.exec(command, options?)

Execute a shell command. Never throws; all errors are returned in the result.

const result = await shell.exec('echo hello', {
  env: { EXTRA: 'value' },   // per-call env vars
  cwd: '/workspace',          // override working directory
  stdin: 'input data',        // provide stdin
  signal: controller.signal,  // AbortSignal for cancellation
  timeout: 5000,              // timeout in milliseconds
});

ExecResult:

interface ExecResult {
  stdout: string;
  stderr: string;
  exitCode: number;
}

State persistence: environment exports, functions, working directory, and filesystem persist across exec() calls. Shell options (set -e, etc.) reset per call.

shell.defineCommand(name, handler)

Register a custom command that works in pipes and redirections.

shell.defineCommand('fetch-url', async (args, ctx) => {
  const response = await fetch(args[0]);
  return { stdout: await response.text(), stderr: '', exitCode: 0 };
});

await shell.exec('fetch-url https://api.example.com | jq .data');

shell.reset()

Clear environment and functions, reset working directory. Filesystem is kept intact.

Accessors

• shell.fs - the virtual FileSystem instance
• shell.cwd - current working directory
• shell.env - environment variables (Map)

Supported Bash Features

• Pipes and redirections (|, >, >>, <, 2>&1, &>)
• Variables and expansion ($VAR, ${VAR:-default}, ${VAR/pattern/replace})
• Control flow (if/elif/else/fi, for/while/until, case/esac)
• Functions with local variables
• Arrays and arithmetic ($((expr)))
• Command substitution ($(cmd), `cmd`)
• Here documents (<<EOF)
• Glob expansion (*, ?, [...])
• Brace expansion ({a,b}, {1..10})
• set -euo pipefail
• Subshells ((cmd))
• Conditional expressions ([[ ]], [ ])

Commands

Command	Description
cat	Concatenate and print files
cp	Copy files
mv	Move/rename files
rm	Remove files
mkdir	Create directories
rmdir	Remove empty directories
touch	Create empty files or update timestamps
chmod	Change file permissions
ln	Create symbolic links
stat	Display file status
file	Determine file type
grep	Search file contents (-i, -v, -c, -l, -n, -r, -w, -E)
sed	Stream editor (s, d, p, i, a, c, y commands; -i, -n, -e)
awk	Pattern scanning (print, if/else, variables, field splitting)
head	Output first lines (-n, -c)
tail	Output last lines (-n, -c, -f)
sort	Sort lines (-r, -n, -u, -k, -t)
uniq	Filter duplicate lines (-c, -d, -u)
wc	Count lines, words, characters (-l, -w, -c, -m)
cut	Remove sections from lines (-d, -f, -c)
tr	Translate characters (-d, -s)
rev	Reverse lines
tac	Reverse file line order
paste	Merge lines from files (-d)
fold	Wrap lines (-w, -s)
comm	Compare sorted files
join	Join lines on a common field
nl	Number lines
expand	Convert tabs to spaces
unexpand	Convert spaces to tabs
strings	Print printable strings
column	Format into columns (-t, -s)
find	Search for files (-name, -type, -path, -maxdepth)
xargs	Build commands from stdin (-I, -n)
diff	Compare files
base64	Encode/decode base64 (-d)
md5sum	Compute MD5 hash
sha1sum	Compute SHA-1 hash
sha256sum	Compute SHA-256 hash
expr	Evaluate expressions
od	Octal dump
ls	List directory contents (-l, -a, -R, -1)
pwd	Print working directory
tree	Display directory tree
du	Estimate file space usage
basename	Strip directory from path
dirname	Strip filename from path
readlink	Read symbolic link target
realpath	Resolve canonical path
echo	Print arguments (-n, -e)
printf	Format and print
env	Display environment
printenv	Print environment variables
date	Display date/time
seq	Print number sequence
hostname	Print hostname
whoami	Print current user
which	Locate a command
tee	Duplicate stdin to file and stdout
sleep	Pause execution
yes	Repeat a string (output-capped)
timeout	Run command with time limit
xxd	Hex dump (-l, -s)
curl	HTTP requests via network handler
jq	JSON processor (full implementation)

jq Support

Full jq implementation built from scratch. Supports identity, field access, array/object indexing, pipe, array/object construction, conditionals, try/catch, reduce, foreach, label/break, string interpolation, user-defined functions, and 80+ builtins including map, select, keys, values, has, in, contains, test, match, sub, gsub, split, join, ascii_downcase, ascii_upcase, tostring, tonumber, length, type, empty, error, env, path, getpath, setpath, delpaths, to_entries, from_entries, with_entries, group_by, sort_by, unique_by, min_by, max_by, flatten, range, floor, ceil, round, pow, log, sqrt, nan, infinite, isinfinite, isnan, isnormal, add, any, all, limit, first, last, nth, indices, inside, ltrimstr, rtrimstr, startswith, endswith, ascii, explode, implode, tojson, fromjson, @base64, @base64d, @uri, @csv, @tsv, @html, @json, @text, now, todate, fromdate, strftime, strptime, gmtime, mktime, builtins, debug, input, inputs, $ENV.

Available as a standalone import:

import { jq } from '@mylocalgpt/shell/jq';

Execution Limits

All limits are configurable via the limits constructor option.

Limit	Default	Prevents
maxLoopIterations	10,000	Infinite loops
maxCallDepth	100	Stack overflow from recursion
maxCommandCount	10,000	Excessive command execution
maxStringLength	10,000,000	Memory exhaustion from string growth
maxArraySize	100,000	Memory exhaustion from array growth
maxOutputSize	10,000,000	Unbounded output accumulation
maxPipelineDepth	100	Deeply nested pipes

Custom Commands

const shell = new Shell({
  commands: {
    'fetch-data': async (args, ctx) => {
      const url = args[0];
      const response = await fetch(url);
      return { stdout: await response.text(), stderr: '', exitCode: 0 };
    },
  },
});

// Or after construction:
shell.defineCommand('transform', async (args, ctx) => {
  return { stdout: ctx.stdin.toUpperCase(), stderr: '', exitCode: 0 };
});

Custom commands receive the full CommandContext and participate in pipes, redirections, and all shell features.

Hooks

onUnknownCommand

Handle commands not in the registry:

const shell = new Shell({
  onUnknownCommand: async (name, args, ctx) => {
    if (name === 'python') {
      return { stdout: '', stderr: `${name}: use jq for data processing\n`, exitCode: 127 };
    }
    return { stdout: '', stderr: `${name}: command not found\n`, exitCode: 127 };
  },
});

onOutput

Post-process all exec results (truncate, redact, log):

const shell = new Shell({
  onOutput: (result) => ({
    ...result,
    stdout: result.stdout.slice(0, 30000), // truncate large output
  }),
});

OverlayFs

Read-through overlay that reads from a real host directory and writes to memory. The host filesystem is never modified.

import { Shell } from '@mylocalgpt/shell';
import { OverlayFs } from '@mylocalgpt/shell/overlay';

const overlay = new OverlayFs('/path/to/project', {
  denyPaths: ['*.env', '*.key', 'node_modules/**'],
});
const shell = new Shell({ fs: overlay });

await shell.exec('cat src/index.ts | wc -l');
await shell.exec('echo "new file" > output.txt');

const changes = overlay.getChanges();
// { created: [{ path: '/output.txt', content: 'new file\n' }], modified: [], deleted: [] }

Available as a separate entry point at @mylocalgpt/shell/overlay. Requires Node.js (uses node:fs).

Network Config

curl delegates all HTTP requests to a consumer-provided handler. The shell never makes real network requests.

const shell = new Shell({
  network: {
    handler: async (url, opts) => {
      const res = await fetch(url, { method: opts.method, headers: opts.headers, body: opts.body });
      return { status: res.status, body: await res.text(), headers: {} };
    },
    allowlist: ['api.example.com', '*.internal.corp'],
  },
});

await shell.exec('curl -s https://api.example.com/data | jq .results');

Security Model

See THREAT_MODEL.md for the full security model, threat analysis, and explicit non-goals.

What we do:

• All user-provided regex goes through pattern complexity checks and input-length caps
• Execution limits prevent infinite loops, deep recursion, and memory exhaustion
• No eval() or new Function() code paths
• Path traversal prevention via normalized absolute paths
• Environment variables stored in Map (no prototype pollution)
• No node: imports; runs in sandboxed environments

What we don't do:

• This is not an OS-level sandbox. The shell executes within your JavaScript runtime's security context.
• Custom commands have full access to the JavaScript environment. Use OS-level isolation for untrusted code.

License

Apache-2.0