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 fetch the extras bundle and its selected dependencies and produce ./jsh-extras, run:

make extras

The optional bundle currently covers 21 selectable groups, including built-in coreutils, mux, encrypted embed/pass/vault storage, SSH, YubiKey, AWS, the encrypted jdrive S3 drive, recording, terminal system tools and process monitoring, wormhole, 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 prompts for optional feature selection and embed input. Pass JSH_FEATURES=... make extras for unattended builds; the extras guide shows the encrypted embed options.

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