|
|
|
|
@@ -34,17 +34,18 @@ brew install coreutils gnu-tar jq
|
|
|
|
|
```
|
|
|
|
|
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`, prepares a per-project state directory, and runs `login` if `${HOME}/.codex/auth.json` is missing or empty.
|
|
|
|
|
- verifies the selected backend CLI hash,
|
|
|
|
|
- creates `${HOME}/.codex`, prepares a per-project state directory, and runs `login` if `${HOME}/.codex/auth.json` is missing or empty for the Codex backend.
|
|
|
|
|
|
|
|
|
|
> 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.
|
|
|
|
|
> Use `./sloptrap path/to/project shell` to enter a troubleshooting shell inside the container or `./sloptrap path/to/project clean` to remove cached images, state, and the project tools volume.
|
|
|
|
|
|
|
|
|
|
## How It Works
|
|
|
|
|
|
|
|
|
|
- The project directory mounts at `/workspace`; project-scoped Codex state mounts at `/codex` from `${HOME}/.codex/sloptrap/state/<project-hash>`, and shared auth mounts from `${HOME}/.codex/auth.json` to `/codex/auth.json`.
|
|
|
|
|
- The project directory mounts at `/workspace`; project-scoped state mounts at `/codex` from `${HOME}/.codex/sloptrap/state/<project-hash>`. Codex also mounts shared auth from `${HOME}/.codex/auth.json` to `/codex/auth.json`; opencode does not.
|
|
|
|
|
- Each project also gets a dedicated engine-managed volume mounted at `/sloptrap-tools`, with `/sloptrap-tools/bin` prepended to `PATH`. This is the supported writable install prefix for third-party agent tools and is kept outside the mounted home/state tree.
|
|
|
|
|
- `.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 helper Dockerfile is embedded inside `sloptrap`. 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.
|
|
|
|
|
|
|
|
|
|
@@ -53,7 +54,7 @@ brew install coreutils gnu-tar jq
|
|
|
|
|
The manifest is optional. When absent, sloptrap derives:
|
|
|
|
|
- `name = basename(project directory)`
|
|
|
|
|
- `packages_extra = ""` (none)
|
|
|
|
|
- `capabilities = ""` (none)
|
|
|
|
|
- `agent = "codex"` (default AI backend)
|
|
|
|
|
If a build is requested and no `.sloptrap` exists, sloptrap prompts to create one interactively.
|
|
|
|
|
|
|
|
|
|
Supported keys when the manifest is present:
|
|
|
|
|
@@ -62,13 +63,19 @@ Supported keys when the manifest is present:
|
|
|
|
|
| --- | --- | --- |
|
|
|
|
|
| `name` | project directory name | Must match `^[A-Za-z0-9_.-]+$`. Used for image/container naming. |
|
|
|
|
|
| `packages_extra` | *empty* | Additional Debian packages installed during `docker/podman build`. Tokens must be alphanumeric plus `+.-`. |
|
|
|
|
|
| `capabilities` | *empty* | Optional privileged features. Supported values are `apt-install` and `packet-capture`. Capability-enabled runs require Podman. When `packet-capture` is combined with `allow_host_network=true`, sloptrap shows a runtime warning with concrete consequences and requires an interactive acknowledgement on every run. |
|
|
|
|
|
| `agent` | `codex` | AI backend: `codex` (OpenAI Codex CLI) or `opencode` (Anomaly opencode CLI). |
|
|
|
|
|
| `opencode_server` | `http://localhost:8080` | OpenAI-compatible server URL (opencode only). Supports llama.cpp, Ollama, vLLM, etc. |
|
|
|
|
|
| `opencode_model` | `bartowski/Qwen_Qwen3.5-9B-GGUF:Q8_0` | Model name on the server (opencode only). |
|
|
|
|
|
| `opencode_context` | `256K` | Context window for the opencode model. Accepts an integer optionally suffixed with `K`, `M`, or `G`. |
|
|
|
|
|
| `allow_host_network` | `false` | `true` opts into `--network host`; keep `false` unless the project absolutely requires direct access to host-local services. |
|
|
|
|
|
|
|
|
|
|
Values containing `$`, `` ` ``, or newlines are rejected to prevent command injection. Setting illegal keys or malformed values aborts the run before containers start.
|
|
|
|
|
sloptrap always runs Codex with `--sandbox danger-full-access --ask-for-approval never`. `codex_args` is deprecated and rejected if present.
|
|
|
|
|
|
|
|
|
|
Capability trust is local state, not part of the repository. Builds for manifests that request capabilities require either an interactive trust confirmation or `--trust-capabilities`. Once the current manifest is trusted, its requested capabilities are enabled automatically for that project configuration. The `allow_host_network=true` plus `packet-capture` combination still requires a separate interactive acknowledgement each time a runtime container is launched.
|
|
|
|
|
### AI Backends
|
|
|
|
|
|
|
|
|
|
**Codex** (default): Uses OpenAI Codex CLI with state stored in `~/.codex/`. Supports login mode for credential sharing.
|
|
|
|
|
|
|
|
|
|
**opencode**: Uses Anomaly opencode CLI with project-scoped state and config stored under sloptrap's per-project state directory. sloptrap downloads the latest Linux CLI release artifact from Anomaly during image builds, verifies its digest from the GitHub release metadata, and copies it into the container image. Connects to any OpenAI-compatible inference server (llama.cpp, Ollama, vLLM, etc.). When `opencode_server` points at `localhost` under isolated networking, sloptrap rewrites it to `http://sloptrap.host:...` so host-local model servers remain reachable from inside the container. No Codex auth file is mounted for opencode sessions.
|
|
|
|
|
|
|
|
|
|
### `.sloptrapignore`
|
|
|
|
|
|
|
|
|
|
@@ -80,26 +87,35 @@ Capability trust is local state, not part of the repository. Builds for manifest
|
|
|
|
|
## CLI Reference
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
./sloptrap [--dry-run] [--print-config] [--trust-capabilities] <code-directory> [target ...]
|
|
|
|
|
./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.
|
|
|
|
|
- `--trust-capabilities` — trust the manifest's requested capabilities for the current build flow.
|
|
|
|
|
- `-h, --help` — display usage.
|
|
|
|
|
- `--` — stop option parsing; remaining arguments are treated as targets.
|
|
|
|
|
|
|
|
|
|
Environment variables override manifest values:
|
|
|
|
|
- `SLOPTRAP_AGENT` — override `agent` key (codex or opencode)
|
|
|
|
|
- `SLOPTRAP_OPENCODE_SERVER` — override `opencode_server` key
|
|
|
|
|
- `SLOPTRAP_OPENCODE_MODEL` — override `opencode_model` key
|
|
|
|
|
- `SLOPTRAP_OPENCODE_CONTEXT` — override `opencode_context` key
|
|
|
|
|
- `SLOPTRAP_CONTAINER_ENGINE` — override container engine auto-detection
|
|
|
|
|
|
|
|
|
|
Security-sensitive runtime overrides such as `SLOPTRAP_SECURITY_OPTS_EXTRA`, `SLOPTRAP_ROOTFS_READONLY`, and `SLOPTRAP_NETWORK_NAME` are rejected.
|
|
|
|
|
Build-path overrides such as `SLOPTRAP_DOCKERFILE_PATH`, `SLOPTRAP_CODEX_URL`, `SLOPTRAP_CODEX_ARCHIVE`, and `SLOPTRAP_CODEX_BIN` are also rejected.
|
|
|
|
|
|
|
|
|
|
Behaviour:
|
|
|
|
|
|
|
|
|
|
- Missing manifests are treated as default configuration; when a build is requested, sloptrap runs the interactive wizard if a TTY is available, otherwise it warns and continues with defaults.
|
|
|
|
|
- `SLOPTRAP_CONTAINER_ENGINE` overrides engine auto-detection.
|
|
|
|
|
- If `${HOME}/.codex/auth.json` is absent or empty, sloptrap prepends a login run before executing your targets.
|
|
|
|
|
- If `${HOME}/.codex/auth.json` is absent or empty, sloptrap prepends a login run before executing your targets (Codex only).
|
|
|
|
|
- Fresh interactive `run` sessions receive a launcher-generated startup prompt telling the agent it is inside sloptrap, summarising the resolved manifest/runtime state, and pointing it at `/workspace/.sloptrap` for exact project configuration. `resume` does not inject that prompt again.
|
|
|
|
|
- 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`, requested/enabled capability lists, trust status, resolved paths, and the sanitised ignore mount roots so you can confirm what will be hidden inside the container.
|
|
|
|
|
`--print-config` fields include backend configuration (Codex or opencode), resolved paths, and the sanitised ignore mount roots so you can confirm what will be hidden inside the container.
|
|
|
|
|
|
|
|
|
|
### Regression Suite
|
|
|
|
|
|
|
|
|
|
@@ -112,12 +128,12 @@ Targets are supplied after the code directory. When omitted, sloptrap defaults t
|
|
|
|
|
|
|
|
|
|
| Target | Description |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| `build` | Download Codex (if missing), verify SHA-256, and build the container image. |
|
|
|
|
|
| `build` | Download the selected backend CLI (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 using sloptrap's built-in runtime flags. |
|
|
|
|
|
| `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 shared `${HOME}/.codex/auth.json` credentials. |
|
|
|
|
|
| `run` | Default goal. Runs the container with the selected backend. Codex uses sloptrap's built-in runtime flags; opencode relies on its generated config. |
|
|
|
|
|
| `resume <session-id>` | Continues a backend session inside the container (Codex uses `codex resume`; opencode uses its session flag). |
|
|
|
|
|
| `login` | Starts Codex in login mode to bootstrap shared `${HOME}/.codex/auth.json` credentials. Not supported for opencode. |
|
|
|
|
|
| `shell` | Launches `/bin/bash` inside the container for debugging. |
|
|
|
|
|
| `wizard` | Creates or updates `.sloptrap` interactively (no build); rerun `build` or `rebuild` afterward. |
|
|
|
|
|
| `stop` | Best-effort stop of the running container (if any). |
|
|
|
|
|
@@ -125,31 +141,30 @@ Targets are supplied after the code directory. When omitted, sloptrap defaults t
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
### Capability Helpers
|
|
|
|
|
|
|
|
|
|
When the current manifest's capabilities are trusted and enabled, the container includes helper commands:
|
|
|
|
|
|
|
|
|
|
- `slop-apt install <package...>` for session-scoped package installation.
|
|
|
|
|
- `slopcap capture --interface <iface> [--filter <expr>] [--output <path>] [--stdout]` for non-promiscuous packet capture through a dedicated helper container. Host-network captures require an explicit acknowledgement each run.
|
|
|
|
|
|
|
|
|
|
## Execution Environment
|
|
|
|
|
|
|
|
|
|
- Container engine: Podman or Docker for standard runs. Capability-enabled runs require Podman. Podman uses `--userns=keep-id`; Docker receives the equivalent `--user UID:GID` for standard runs.
|
|
|
|
|
- Filesystem view: the project directory mounts at `/workspace`; `${HOME}/.codex/sloptrap/state/<project-hash>` mounts at `/codex`; `${HOME}/.codex/auth.json` mounts at `/codex/auth.json`.
|
|
|
|
|
- Ignore filter: `.sloptrapignore` entries are overlaid with tmpfs directories or empty bind mounts so data remains unavailable to Codex.
|
|
|
|
|
- Network: isolated networking is used by default; `allow_host_network=true` opts into `--network host`. When `packet-capture` is enabled, sloptrap starts a separate capture helper container in the same Podman pod so the main Codex container does not receive `NET_RAW`.
|
|
|
|
|
- Process context: standard runs drop capabilities, set `no-new-privileges`, use a read-only root filesystem, and keep scratch paths (`/tmp`, `/run`, `/run/lock`) on tmpfs. Capability-enabled runs may selectively add the runtime options required for the requested capability.
|
|
|
|
|
- Codex configuration: runtime flags are fixed to `--sandbox danger-full-access --ask-for-approval never`. Persistent Codex state is project-scoped under `${HOME}/.codex/sloptrap/state/`, while credentials are shared via `${HOME}/.codex/auth.json` and mounted read-only except during the `login` target.
|
|
|
|
|
- Container engine: Podman or Docker for standard runs. Podman uses `--userns=keep-id`; Docker receives the equivalent `--user UID:GID` for standard runs.
|
|
|
|
|
- Filesystem view:
|
|
|
|
|
- **Codex**: project directory at `/workspace`; `${HOME}/.codex/sloptrap/state/<project-hash>` at `/codex`; auth at `/codex/auth.json`.
|
|
|
|
|
- **opencode**: project directory at `/workspace`; `${HOME}/.codex/sloptrap/state/<project-hash>` at `/codex`; generated config at `/codex/config/opencode/opencode.json`; runtime state at `/codex/state/opencode`; no shared auth mount.
|
|
|
|
|
- **Both backends**: per-project tools volume at `/sloptrap-tools`; `/sloptrap-tools/bin` is on `PATH`; `SLOPTRAP_TOOLS_HOME=/sloptrap-tools`.
|
|
|
|
|
- Ignore filter: `.sloptrapignore` entries are overlaid with tmpfs directories or empty bind mounts so data remains unavailable to the agent.
|
|
|
|
|
- Network: isolated networking is used by default; `allow_host_network=true` opts into `--network host`. For isolated runs, sloptrap injects `sloptrap.host` as a container-side hostname for the host gateway. On Podman `slirp4netns`, opencode runs also enable host loopback access so host-local servers bound to `localhost` remain reachable.
|
|
|
|
|
- Process context: standard runs drop capabilities, set `no-new-privileges`, use a read-only root filesystem, and keep scratch paths (`/tmp`, `/run`, `/run/lock`) on tmpfs.
|
|
|
|
|
- Agent configuration:
|
|
|
|
|
- **Codex**: runtime flags fixed to `--sandbox danger-full-access --ask-for-approval never`. Supports login mode for credential sharing.
|
|
|
|
|
- **opencode**: connects to OpenAI-compatible server via `--server` and `--model` flags. No authentication required for self-hosted models.
|
|
|
|
|
|
|
|
|
|
## 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`, project-scoped `/codex`, and `/codex/auth.json` are host mounts. Files written to these locations become visible on the host and to the LLM provider through prompts.
|
|
|
|
|
- **Shared storage**: `/workspace` and project-scoped `/codex` are host mounts. For Codex, `/codex/auth.json` is also mounted from the host; opencode sessions do not receive that shared credential file. Files written to mounted locations become visible on the host and may be surfaced to the configured provider through prompts.
|
|
|
|
|
- **Tools persistence**: `/sloptrap-tools` is a per-project container-engine volume, not a bind mount into `${HOME}`. Anything installed there persists across runs for that project until `clean` removes the volume.
|
|
|
|
|
- **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**: standard runs keep a read-only root filesystem and no extra Linux capabilities. Capability-enabled runs deliberately relax specific runtime controls for the enabled feature, so they should be treated as a stronger trust decision than a default session. `packet-capture` now runs in a dedicated helper container so the main Codex container does not hold raw-socket capability.
|
|
|
|
|
- **Networking stance**: traffic is unrestricted once it leaves the container. sloptrap does not enforce an allowlist or DNS policy. Host networking is opt-in per manifest; when it is combined with `packet-capture`, sloptrap warns and requires an explicit acknowledgement for each runtime launch because the capture helper will have raw packet access in the host namespace and may observe plaintext traffic or inject spoofed packets. If you require an offline or firewalled workflow, sloptrap is not an appropriate launcher.
|
|
|
|
|
- **Process isolation**: standard runs keep a read-only root filesystem and no extra Linux capabilities.
|
|
|
|
|
- **Networking stance**: traffic is unrestricted once it leaves the container. sloptrap does not enforce an allowlist or DNS policy. Host networking is opt-in per manifest. If you require an offline or firewalled workflow, sloptrap is not an appropriate launcher.
|
|
|
|
|
- **Persistence**: Codex history and logs accumulate per project under `${HOME}/.codex/sloptrap/state/`. 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**: per-project state mounts remain writable by the container and hold prompts/history/state, while `${HOME}/.codex/auth.json` holds shared credentials. Rotate credentials regularly and protect both locations.
|
|
|
|
|
- **Codex cache hygiene**: per-project state mounts remain writable by the container and hold prompts/history/state, while `${HOME}/.codex/auth.json` holds shared Codex credentials when that backend is used. Rotate credentials regularly and protect both locations.
|
|
|
|
|
- **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.
|
|
|
|
|
|
|
|
|
|
|
