bot-jail — bj

bj gives coding agents (Codex, OpenCode, jcode) an isolated writable repository and prepared toolchain inside a FreeBSD jail, using ZFS snapshots/clones to share unchanged blocks. Git pull/push works through a narrowly scoped host-side broker. On agent exit the jail is stopped, all session-history artifacts are durably archived (content-addressed, hash verified), temporary datasets are destroyed, and the history is queued for import into jerboa-llm-search.

bj codex ~/mine/jerboa
bj opencode ~/mine/jerboa
bj jcode ~/mine/jerboa

Implemented in Jerboa (.ss). Management logic never builds shell strings: every privileged operation is an argv list executed through (std os aproc) aproc-spawn*. Two reusable libraries are included:

• jerboa-zfs/ — typed, argv-based ZFS wrapper (zfs-get, zfs-clone!, zfs-destroy-exact!, ...). No recursive destroy, no silent success.
• jerboa-jail/ — typed FreeBSD jail wrapper (jail-create!, jail-exec!, jail-stop!, strict jail-config serialization).

Status

See docs/compatibility.md. FreeBSD jail/ZFS execution evidence must be recorded there before any agent support is considered complete. Unit tests run anywhere Jerboa builds; make test-freebsd requires a FreeBSD host with root and a test-owned ZFS pool subtree.

The production batch launcher is verified for OpenCode and Codex under FreeBSD's Linux ABI using Ubuntu Jammy templates. Codex uses OpenAI's complete Linux standalone package inside the template; it is not a native FreeBSD port. The package layout, including codex-code-mode-host and its resources, must be preserved because copying only the codex executable leaves provider requests working while shell tools fail. jcode retains the same batch lifecycle but remains unsupported until its compatibility row carries real provider and tool-use evidence.

Two meanings of saved

• archived — complete native history artifacts are durably stored outside all temporary datasets and their hashes were verified. This permits destruction of run storage.
• indexed — llm-search imported the archive successfully. Parser downtime never requires retaining a whole disposable jail.

Layout

src/entry*.ss            binary entries (bj, bj-hostd, bj-gitbroker,
                         bj-git-transport, bj-jail-entry)
src/bj/*.ss              manager modules (run lifecycle, repo baselines,
                         templates, credentials, network, terminal,
                         git broker/transport, collector, cleanup,
                         history, hostd, CLI)
jerboa-zfs/ jerboa-jail/ reusable libraries
etc/                     config example + FreeBSD rc.d script
tests/unit/              host-agnostic unit tests (run everywhere)
tests/run-freebsd        real zfs+jail lifecycle tier (FreeBSD + root)
tests/run-agents         fixture-agent tier: static agent executes
                         inside a real jail; orphan-stop proof
docs/                    compatibility + acceptance evidence

Build

make binary        # builds bin/bj, bin/bj-hostd, bin/bj-gitbroker,
                   # bin/bj-git-transport and bin/bj-jail-entry
make test-unit     # unit tests (host-agnostic)
make test-freebsd  # FreeBSD real zfs + jail lifecycle (root required)
make test-agents   # fixture agent executes inside a real jail (root)
make smoke         # --version / --help for every binary

Quick host setup (FreeBSD)

1. sudo bj init --dataset tank/bj — creates only the approved manager subtree and root-owned config under /var/db/bj.
2. sudo make install (or copy etc/rc.d/bj to /usr/local/etc/rc.d) and service bj start — runs bj-hostd.
3. bj repo add ~/mine/jerboa — registers the repository.
4. bj template build codex — builds/version the agent template.
5. bj codex ~/mine/jerboa — run the agent in a jail.

Unpushed code and uncommitted edits inside a run are disposable: push during the run, or use bj export-work RUN DEST while a run is live. History archival preserves conversation artifacts, not your code.