yolo-jail: Instructions file for Codex

YOLO Jail: Agent Developer Guide

yolo-jail runs coding agents in an isolated container against a live-mounted workspace, without exposing host credentials or identity.

AGENTS ARE PACKS. Core does not know what an agent is. There is no agent registry, no agents config key, and no YOLO_AGENTS. Config carries ONE list of packs; the fifteen that ship with yolo live in packs/*/pack.json and are selected by BARE NAME — "packs": ["claude"] (counted against ls packs/ 2026-09-04). Six install an agent (claude, copilot, opencode, pi, codex, agy) and nine install no CLI at all, in four kinds: audio, host-processes, journal, cgroup-delegate and serial ship a LOOPHOLE each (audio also contributes two env vars — the only one of the five that ships anything beside its loophole); zai and cerebras ship neither CLI nor loophole — a provider and a profile apiece, the two packs whose whole content is declarative facts (zai the first, cerebras the second); guardrails ships blocked-tool refusals and install requirements (core blocks nothing by default since 9caba669 — the blocked tools are opt-in through it); and wire-bridge is the first kind: "service" pack — one in-jail daemon and its endpoint file, no grants, joined to a launch automatically through cerebras's needs entry when claude or copilot is selected (docs/design/wire-bridge.md §2-§3). Anything that says "the six" is describing the agent SUBSET.

Every loophole yolo ships is a pack's, and there is no other channel (2026-08-19). journal and cgroup-delegate were Go functions the run pipeline called by hand — one switched by a top-level journal config key, the other by nothing at all. audio and host-processes came out of bundled_loopholes/. claude-oauth-broker was the last inhabitant of that directory and is now a contribution of packs/claude, not a pack of its own: the dependency is structural, so selecting the claude pack is the dependency (loophole-activation.md OQ-A10). bundled_loopholes/ and its embed are DELETED. Three consequences worth knowing before touching any of this: paths.BuiltinLoopholeNames and loopholes.ReservedLoopholeNames are both GONE (a reserved name and a pack-shipped name cannot be the same name — the pre-flight is fatal, so it refuses every launch that selects the pack); the top-level journal and host_processes keys are now REFUSALS that name their replacements; and the pack-shipped SUBSET is the only vocabulary left, so publishes: "endpoint", jail_env and an absolute requires.file_exists are refused for every manifest yolo reads — there is no wider-vocabulary source to fall back to.

Nothing is active by default: an empty config yields a jail with no coding agent, and says so at launch (run.warnIfNoPacks). internal/config/validate.go hard-errors on agents on the host (and warns in-jail, where the config is the generated snapshot).

What a pack declares (internal/packdecl), all read through internal/packload: install spec, mounts, writable/shared dirs, host-file grants, composed surfaces, launch flags, and named hooks. The boot path renders every one in a single loop (entrypoint/packsurfaces.go) with no switch on any tool name. Two things worth knowing before you debug:

• The MOUNT is the filter. The entrypoint renders every pack under YOLO_PACK_ROOT, so stagePacks copies only the SELECTED packs into the mounted tree. Staging all six and filtering later renders packs nobody asked for. A dropped pack therefore has to be UNSTAGED or it keeps rendering: _official/ is cleared wholesale (it is derived from the binary's embed.FS), and each configured pack's dir is pruned when its slug leaves packs — contents-only, never the staging root itself, whose inode a live jail's /ctx/packs bind captured (packstage rule 3). A pack still configured but unresolvable this launch (offline git remote) is KEPT, not pruned.
• packload.Embedded* is deliberately NOT selection-gated. The reservation lists (host_files writable roots, writable_home_dirs segments, GlobalHome subdirs) cover every pack yolo SHIPS, or a host_files entry could claim a path a pack added tomorrow needs.
• packload.Embedded() is ONE temp tree for the WHOLE PROCESS, released on the way out. It is materialized before argv is even parsed — internal/config's hostFileWritableRoots is a package-level var whose initializer reaches it — so every yolo invocation pays for it, --version included. Pack.Root is a handle into that tree, nothing can know when the last read happens, and the only exit paths are cli.Main (deferred) and entrypoint.Main (explicit, since execBash replaces the process). A second process-lifetime copy is the bug to watch for: three call sites made their own, each leaking a never-removed ~200 KB directory per invocation (measured live 2026-09-03: 625 dirs, 109 MB) — call MaterializeEmbedded directly only when you delete the dest yourself (internal/cli/run/packs.go stages out of one).