jerboa-shell

jerboa-shell is jsh: a compact shell written in Jerboa Scheme. It focuses on familiar bash/zsh-style command execution: parsing, expansion, builtins, redirection, pipelines, jobs, history, completion, and POSIX process behavior.

Security posture, threat model, native-boundary notes, and release evidence are tracked in SECURITY.md, docs/threat-model.md, docs/ffi-boundary.md, and docs/release-evidence.md. jsh is a shell, not a sandbox.

Build

make jsh-macos
./jsh-macos -c 'echo ok'

The build uses jerbuild from Jerboa. The Makefile prefers ./jerbuild, then .jerboa/bin/jerbuild, then jerbuild on PATH; if none are available it fetches the configured Jerboa release tool.

The default targets build only the bare shell. To open the optional-feature menu, fetch the extras bundle and its selected dependencies, and produce ./jsh-extras, run:

make extras

The optional bundle currently covers 20 selectable groups, including built-in coreutils, mux, encrypted embed/pass/vault storage, SSH, YubiKey, AWS, wormhole, recording, sandboxing, resource limits, profiling, proxying, WireGuard, process watching, hardening, AWK, and sed. See docs/extras.md for the complete command reference, selection rules, platform requirements, security boundaries, and known limitations.

The top-level target uses _vendor/jerboa-shell-extras/embed as its embed input. It does not automatically read or encrypt ~/.embed; the extras guide shows the explicit encrypted build command.

Test

make test
make test-native
make test-security-regressions
make audit
make release-evidence
make test-binary
make compat-smoke

The Oils spec runner under test/ measures shell compatibility. Benchmark scripts live here so speed work stays close to the shell implementation. make release-evidence records unit tests, native FFI audit output, SBOM manifests, and reproducibility output under dist/release-evidence/.

Command substitution is drained concurrently and is limited to 8 MiB by default. Set JSH_COMMAND_SUB_MAX_BYTES to a positive byte limit no greater than 1 GiB when a workload needs a different bound. Exceeding the limit aborts the expansion after the producer has been drained, rather than hanging it on a full pipe.

Interpreted development runs load libjsh-ffi only when JSH_FFI_DEV_NATIVE=1 and JSH_FFI_LIB names an absolute, non-symlink directory. Standalone builds register the shim statically; neither mode searches the current directory or a bare library name. Development loading also rejects ambient DYLD/LD search overrides and verifies the JSH1 ABI canary.

History

Interactive jsh writes normal line-oriented shell history to $HISTFILE (default: ~/.jsh_history). Set HISTSIZE and HISTFILESIZE to control the in-memory and saved entry limits.

History recording can be disabled from startup config with the bash-style history option:

# ~/.jshrc
case "$PWD/" in
  "$HOME/mine/obersh/"*) set +o history ;;
esac

For memory-only session history without saving a file, unset HISTFILE, set HISTFILE=, or set HISTFILE=/dev/null.

Layout

*.ss                  shell source modules
jerboa-src/src/       small compatibility modules used by the build
support/              build helpers
test/                 unit, binary, and Oils compatibility tests
bench*.ss             shell benchmark scripts