sloptrap

sloptrap runs the OpenAI Codex CLI inside a container with a predictable and locked-down filesystem view. The launcher script (sloptrap) resolves the project manifest, builds the support image directly, and starts Codex with the requested target (defaults to run). Hardened parsing blocks container escapes via manifest or ignore directives, verifies the downloaded Codex binary, and keeps the runtime environment minimal.

Dependencies

• Podman ≥ 4 (sloptrap refuses to run without it unless you explicitly override SLOPTRAP_CONTAINER_ENGINE).
• GNU bash, curl, tar, sha256sum, realpath (from GNU coreutils), and jq on the host.

Tip: set SLOPTRAP_CONTAINER_ENGINE=<engine> if you need to override the default Podman requirement.

macOS setup

sloptrap targets GNU userland. On macOS, install the GNU tools via Homebrew and the launcher will prepend their gnubin paths automatically:

brew install coreutils gnu-tar jq

Quick Start

1. Place sloptrap somewhere on your PATH/shared drive (the helper Dockerfile and Codex binary are bundled and downloaded automatically).
2. (Optional) Create a project-specific manifest and ignore file:

   cat > path/to/project/.sloptrap <<'EOF'
   name=path/to/project
   default_targets=run
   packages_extra=make
   codex_args=--sandbox workspace-write 
   EOF
   
   cat > path/to/project/.sloptrapignore <<'EOF'
   .git/
   secrets/
   EOF
   

3. Run ./sloptrap path/to/project. On the first invocation sloptrap:
   • builds path/to/project-sloptrap-image if missing,
   • verifies the Codex binary hash,
   • creates ${HOME}/.codex and runs login if credentials are absent.

Use ./sloptrap path/to/project shell to enter a troubleshooting shell inside the container or ./sloptrap path/to/project clean to remove cached images and state.

How It Works

• The project directory mounts at /workspace, and ${HOME}/.codex mounts at /codex.
• .sloptrapignore entries (if present in your project) are overlaid by tmpfs (for directories) or empty bind mounts (for files) so Codex cannot read the masked content.
• sloptrap launches containers on an isolated network (bridge on Docker, slirp4netns on Podman) with --cap-drop=ALL, --security-opt no-new-privileges, a read-only root filesystem, and tmpfs-backed /tmp, /run, and /run/lock. Projects that explicitly set allow_host_network=true in their manifest opt into --network host.
• The helper Dockerfile is embedded inside sloptrap; set SLOPTRAP_DOCKERFILE_PATH=/path/to/custom/Dockerfile if you need to supply your own recipe. The default image installs curl, bash, ca-certificates, libstdc++6, git, ripgrep, xxd, and file, so most debugging helpers are already available without adding packages_extra.
• The container user matches the host UID/GID (--userns=keep-id on Podman or --user UID:GID on Docker).
• The runtime environment is fixed to HOME/XDG variables pointing at /codex; manifest-controlled environment injection is disabled.

.sloptrap Manifest Reference

The manifest is optional. When absent, sloptrap derives:

• name = basename(project directory)
• default_targets = run
• packages_extra = "" (none)
• codex_args = "--sandbox workspace-write"

Supported keys when the manifest is present:

Key	Default	Notes
name	project directory name	Must match ^[A-Za-z0-9_.-]+$. Used for image/container naming.
default_targets	run	Space-separated targets invoked when none are provided on the CLI.
packages_extra	empty	Additional Debian packages installed during docker/podman build. Tokens must be alphanumeric plus +.-.
codex_args	--sandbox workspace-write	Passed verbatim to the Codex CLI entrypoint. Tokens are shell-split, so quote values with spaces (e.g., --profile security-audit).
allow_host_network	false	true opts into --network host; keep false unless the project absolutely requires direct access to host-local services.
codex_args are appended after the default sandbox flag, and sloptrap refuses to run if the resulting --sandbox mode is anything other than workspace-write or workspace-read-only.

Values containing $, `, or newlines are rejected to prevent command injection. Setting illegal keys or malformed values aborts the run before containers start.

.sloptrapignore

• Parsed using gitignore-style globbing with support for !negation.
• Entries must stay within the project root after resolving symlinks; attempts to reference ./.., absolute paths, or symlink escapes raise errors.
• Directory matches become --mount type=tmpfs,target=/workspace/<path>. File matches bind to empty files within .sloptrap-ignores/session-<pid>/.
• The helper directory is removed automatically on exit or during ./sloptrap <project> clean.

CLI Reference

./sloptrap [--dry-run] [--print-config] <code-directory> [target ...]

Options:

• --dry-run — print the container/engine commands that would run without executing them.
• --print-config — output the resolved manifest values, defaults, and ignore list.
• -h, --help — display usage.
• -- — stop option parsing; remaining arguments are treated as targets.

Behaviour:

• Missing manifests are treated as default configuration.
• SLOPTRAP_CONTAINER_ENGINE overrides engine auto-detection.
• If ${HOME}/.codex/auth.json is absent, sloptrap prepends a login run before executing your targets.
• Exit status mirrors the last target executed; errors in parsing or setup abort early with a message.

--print-config fields include manifest_present=true|false, resolved paths, and the sanitised ignore mount roots so you can confirm what will be hidden inside the container.

Regression Suite

• make regress (or tests/run_tests.sh) runs shellcheck against sloptrap and then executes every scenario in tests/run_tests.sh, including the container build path check.
• The suite must pass cleanly; ShellCheck diagnostics or scenario regressions cause a non-zero exit and should be fixed before shipping changes.

Built-in Targets

Targets are supplied after the code directory (or via default_targets in the manifest). When omitted, sloptrap defaults to run.

Target	Description
build	Download Codex (if missing), verify SHA-256, and build the container image.
build-if-missing	No-op when the image already exists; otherwise delegates to build.
rebuild	Rebuild the image from scratch (--no-cache).
run	Default goal. Runs the container with Codex as entrypoint and passes codex_args.
resume <session-id>	Continues a Codex session by running codex resume <session-id> inside the container (builds if needed).
login	Starts Codex in login mode to bootstrap ${HOME}/.codex.
shell	Launches /bin/bash inside the container for debugging.
stop	Best-effort stop of the running container (if any).
clean	Removes .sloptrap-ignores, deletes the container/image, and stops the container if necessary.

The launcher executes targets sequentially, so ./sloptrap repo build run performs an explicit rebuild before invoking Codex. Extra targets may be added in the future; unknown names fail fast.

Execution Environment

• Container engine: Podman or podman with identical command lines. Podman uses --userns=keep-id; Docker receives the equivalent --user UID:GID.
• Filesystem view: the project directory mounts at /workspace; ${HOME}/.codex mounts at /codex.
• Ignore filter: .sloptrapignore entries are overlaid with tmpfs directories or empty bind mounts so data remains unavailable to Codex.
• Network: the container always runs with --network host. sloptrap does not filter or proxy outbound traffic.
• Process context: capabilities are dropped, no-new-privileges is set, the root filesystem is read-only, and scratch paths (/tmp, /run, /run/lock) are tmpfs mounts. Resource limits follow the launcher defaults.
• Codex configuration: runtime flags come from codex_args. Persistent Codex state is stored under ${HOME}/.codex.

Threat Model and Limits

• Outbound disclosure: prompts and referenced data travel from the container to the configured LLM endpoint. Any file content within /workspace or environment data exposed to the process can appear in that traffic.
• Shared storage: /workspace and /codex are the only host mounts. Files written to these locations become visible on the host and to the LLM provider through prompts.
• Environment surface: the container receives a minimal fixed environment (HOME/XDG paths, CODEX_HOME). The manifest no longer allows injecting additional environment variables.
• Process isolation: the container runs without additional Linux capabilities and with a read-only root filesystem. The container and host still share the same kernel; a kernel-level escape would affect host confidentiality.
• Networking stance: traffic is unrestricted once it leaves the container. sloptrap does not enforce an allowlist or DNS policy, and --network host is always used because the bundled Codex CLI must reach an upstream LLM provider. If you require an offline or firewalled workflow, sloptrap is not an appropriate launcher.
• Persistence: Codex history and logs accumulate under ${HOME}/.codex. Sensitive prompts recorded on disk remain on the host after the session. Because .git/ is ignored inside the container, any historical secrets in Git objects stay outside the LLM context unless explicitly surfaced in the working tree.
• Codex cache hygiene: the ${HOME}/.codex mount remains writable by the container and will hold tokens, cached prompts, and other state. Rotate credentials regularly and avoid co-locating unrelated secrets inside that directory.
• Secret scanning: sloptrap does not perform secret discovery or redaction; any credentials present in the project remain available to Codex and the upstream provider.
• Local model exception: pointing Codex at a local or self-hosted model keeps data within the host network boundary, but the filesystem and environment exposure described above is unchanged.

These constraints focus on limiting host data exposure to the Codex session while acknowledging that any material introduced into the context window may leave the environment through the upstream API.