cli-agent-runner 0.2.20__tar.gz → 0.2.21__tar.gz

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/.vulture-whitelist.py

@@ -133,6 +133,7 @@ prompt_arg_template
 name
 env
 prompt_delivery
+exec_prefix
 
 # agent_runner.config.models.Config
 agent

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.21] - 2026-09-11
+
+### Added
+- `[agent] exec_prefix`: an optional token list prepended to the agent command at spawn (with `{work_dir}` substituted), so the agent can run inside a container you supply (`docker`/`podman run …`) while agent-runner supervises the resulting process from outside. The agent's identity — throttle, crash-loop, usage plugins — still keys on `command`, unchanged.
+- Startup check: a stdin-delivery agent whose container `exec_prefix` omits `-i`/`--interactive` now fails loudly at boot instead of silently hanging until the round-timeout kill.
+- Docs: container recipes (`docs/recipes/container-pi.md`, with Kimi/Claude/rootless-podman deltas), an all-in-one deploy recipe (`deploy/` + `docs/recipes/deploy-all-in-one.md`), and a `SECURITY.md` containment section.
+
+### Fixed
+- The best-effort container stop no longer reports a false "stop failed" when a `--rm` container has already exited on its own; an already-removed container now counts as a successful stop.
+
+### Notes
+- Not breaking: no `agent-runner migrate` step, no systemd unit change.
+
 ## [0.2.20] - 2026-09-09
 
 ### Fixed

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.20
+Version: 0.2.21
 Summary: Restart-on-exit supervisor for autonomous CLI agents
 Project-URL: Homepage, https://github.com/wan9yu/cli-agent-runner
 Project-URL: Documentation, https://github.com/wan9yu/cli-agent-runner#readme

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/SECURITY.md

@@ -37,6 +37,26 @@ unprivileged user, inside a container or VM, without passwordless sudo, and
 with egress limits. The supervisor's defenses bound the blast radius of a
 *misbehaving* agent, not a *hostile* one.
 
+## Containment
+
+If you need to bound what the agent can reach, run it inside a container (or
+VM) you supply, via `[agent] exec_prefix` — see
+[docs/recipes/container-pi.md](docs/recipes/container-pi.md). The container
+(or VM) enforces the isolation; agent-runner still just watches the
+resulting process from outside, the same way it watches a bare agent
+process.
+
+One limit worth knowing: agent-runner's own process-tree defenses (reaping a
+hung round's descendants) only see processes in its own subtree, and a
+container-runtime-managed process usually isn't one of them. On a stuck
+round, the one remaining lever is stopping the container by the id
+agent-runner captured at spawn, which only works for a plain `docker
+run …`/`podman run …` invocation — not one wrapped in `sudo` or other global
+flags (see container-pi.md's footguns). Using a container this way gives you
+a narrower safety net than the host-level reaping a bare agent process gets,
+not a wider one — keep running it as a dedicated unprivileged user with no
+passwordless sudo and tight egress limits regardless.
+
 ## Scope
 
 In scope: the `agent_runner` Python package, its CLI, its bundled systemd

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.20'
-__version_tuple__ = version_tuple = (0, 2, 20)
+__version__ = version = '0.2.21'
+__version_tuple__ = version_tuple = (0, 2, 21)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/agent_runner/agent_runtime.py

@@ -26,6 +26,11 @@ from agent_runner.clock import SYSTEM_CLOCK, Clock
 
 REAP_GRACE_S = 5
 
+# Wall-clock bound on the best-effort `<runtime> stop` subprocess. Pinned by an
+# invariant test to stay <= _serve_policy._ROUND_TERM_GRACE_S so serve's
+# round-terminate escalation never SIGKILLs round_cmd mid-stop.
+_CONTAINER_STOP_TIMEOUT_S = REAP_GRACE_S + 5
+
 # Backstop cap on the stored child "name" (see _live_children). The primary
 # source (kernel comm) is already bounded (15 bytes on Linux); this only
 # guards the argv[0]-basename fallback used when comm is unavailable.
@@ -362,6 +367,20 @@ def _detect_container_run(command: list[str]) -> tuple[str, int] | None:
     return None
 
 
+# Matches the docker/podman flags that attach the container's stdin: `-i`, any
+# short cluster containing `i` (`-it`, `-ti`, `-di`), and `--interactive[=…]`;
+# NOT `--init` (double-dash, so the single-dash alternative can't consume it).
+_INTERACTIVE_FLAG = re.compile(r"^(-[a-z]*i[a-z]*|--interactive(=.*)?)$")
+
+
+def _exec_prefix_is_interactive(exec_prefix: list[str]) -> bool:
+    """True when the operator's ``exec_prefix`` carries a stdin-attaching flag.
+    Only the prefix's own docker flags matter -- the wrapped ``command`` runs
+    INSIDE the container, so an ``-i`` there is irrelevant to whether the
+    runtime forwards stdin."""
+    return any(_INTERACTIVE_FLAG.match(tok) for tok in exec_prefix)
+
+
 # `docker run`/`podman run` OPTIONS known to take a separate value token --
 # used only to walk PAST them without mistaking their value for IMAGE (e.g.
 # `--name foo`: without this, a naive scan would stop at "foo" thinking it's
@@ -479,10 +498,12 @@ def _best_effort_container_stop(
     ``(container_id, stop_ok)``: `container_id` is None when no id could be
     recovered (the container never actually started, or the cidfile is still
     empty) -- `stop_ok` is then also None, meaning no stop was attempted.
-    Otherwise `stop_ok` is whether the `stop` subprocess exited zero. Every
-    failure here is swallowed -- this is advisory best-effort, never a
-    guarantee; the caller's loud warning + event is the actual floor when
-    this doesn't land."""
+    Otherwise `stop_ok` is True when the `stop` subprocess exited zero, or
+    when it failed because the container was already gone (a `--rm`
+    container can self-remove before our stop lands -- that's not a failure
+    to report). Every other failure here is swallowed -- this is advisory
+    best-effort, never a guarantee; the caller's loud warning + event is the
+    actual floor when this doesn't land."""
     if cidfile is None:
         return None, None
     try:
@@ -493,12 +514,16 @@ def _best_effort_container_stop(
         return None, None
     try:
         result = subprocess.run(
-            [runtime, "stop", cid],
+            [runtime, "stop", "-t", str(REAP_GRACE_S), cid],
             stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            timeout=10,
+            stderr=subprocess.PIPE,
+            timeout=_CONTAINER_STOP_TIMEOUT_S,
         )
-        return cid, result.returncode == 0
+        if result.returncode == 0:
+            return cid, True
+        # A `--rm` container that already exited is GONE, not orphaned — not a failure.
+        stderr = (result.stderr or b"").decode("utf-8", "replace").lower()
+        return cid, "no such container" in stderr
     except (OSError, subprocess.TimeoutExpired):
         return cid, False
 

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/agent_runner/cli/serve_cmd.py

@@ -29,6 +29,7 @@ from agent_runner._throttle import (
     round_outcome,
     round_was_mem_terminated,
 )
+from agent_runner.agent_runtime import _detect_container_run
 from agent_runner.api import (
     check_self_terminated_sentinel,
     emit_config_broken,
@@ -611,7 +612,9 @@ def cmd(args) -> int:
         return fail_code
     stop_file = cfg.runtime.stop_file  # cache: same pattern as effective_max_rounds
     work_dir = cfg.runtime.work_dir
-    defer_to_cgroup = _probe_and_emit_cgroup_defer(log_dir)
+    # Emitted exactly once per serve lifetime -- the per-round defer decision below
+    # reuses this bool rather than re-probing/re-emitting every round.
+    cgroup_probe_defer = _probe_and_emit_cgroup_defer(log_dir)
     rounds_completed = 0
     # Three independent consecutive-failure counters, one per breaker: b12
     # crash-loop (unknown short crashes), mem-loop (mem-terminated
@@ -685,6 +688,15 @@ def cmd(args) -> int:
             ]
             if phase_arg is not None:
                 round_argv += ["--phase", phase_arg]
+            # Phase-aware, per-round: a phase can override [phases.<name>.agent]
+            # command to a bare container run even when the base agent isn't one
+            # (exec_prefix is base-only, but command isn't) -- computing this once
+            # from the base agent would wrongly keep deferring a containerized
+            # phase's mid-round kill to dockerd's own cgroup-OOM.
+            defer_to_cgroup = cgroup_probe_defer and (
+                _detect_container_run(cfg.profile_for(phase_arg).agent.spawn_command(work_dir))
+                is None
+            )
             r_returncode = _spawn_round(
                 round_argv,
                 round_log_path,

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/agent_runner/config/models.py

@@ -30,6 +30,7 @@ class AgentConfig:
     name: str | None = None
     env: dict[str, str] = field(default_factory=dict)
     prompt_delivery: Literal["argv", "stdin"] = "argv"
+    exec_prefix: list[str] = field(default_factory=list)
 
     @property
     def binary(self) -> str | None:
@@ -40,6 +41,16 @@ class AgentConfig:
         serve and runner don't each re-spell ``Path(command[0]).name``."""
         return Path(self.command[0]).name if self.command else None
 
+    def spawn_command(self, work_dir: Path) -> list[str]:
+        """The effective argv to spawn: an opaque operator-supplied ``exec_prefix``
+        (e.g. ``docker run … img``) spliced BEFORE ``command``, with the one
+        ``{work_dir}`` token substituted IN THE PREFIX ONLY. ``command`` (and thus
+        ``binary``) is appended verbatim and never rewritten, so the
+        throttle/crash-loop/hook identity join stays keyed on the real agent. Empty
+        ``exec_prefix`` ⇒ ``command`` unchanged. The SSOT both the spawn (runner) and
+        the startup battery resolve, so they can't drift."""
+        return [t.replace("{work_dir}", str(work_dir)) for t in self.exec_prefix] + self.command
+
 
 @dataclass(frozen=True)
 class RuntimeConfig:

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/agent_runner/config/parsers.py

@@ -106,12 +106,16 @@ def _parse_agent(
             f"{field_prefix} command: must be a non-empty list; run `agent-runner migrate`"
         )
     env_d = _require_table(agent_d, "env", label=f"{field_prefix.strip('[]')}.env")
+    exec_prefix = _require_str_list(
+        agent_d.get("exec_prefix", []), field=f"{field_prefix} exec_prefix"
+    )
     return AgentConfig(
         command=command,
         prompt_arg_template=prompt_arg_template,
         name=agent_d.get("name"),
         env={str(k): str(v) for k, v in env_d.items()},
         prompt_delivery=prompt_delivery,  # type: ignore[arg-type]  # narrowed above
+        exec_prefix=exec_prefix,
     )
 
 
@@ -214,6 +218,11 @@ def _parse_phase_overrides(
             agent_sub = value["agent"]
             if not isinstance(agent_sub, dict):
                 raise ConfigError(f"[phases.{phase_name}.agent] must be a table")
+            if "exec_prefix" in agent_sub:
+                raise ConfigError(
+                    f"[phases.{phase_name}.agent] exec_prefix: not allowed per-phase — set "
+                    "exec_prefix once on the base [agent] table (it applies to every phase)"
+                )
             merged = {**agent_d, **agent_sub}
             phase_agent = _parse_agent(
                 merged,

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/agent_runner/runner.py

@@ -554,7 +554,7 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
         )
 
     result = agent_runtime.run(
-        command=profile.agent.command,
+        command=profile.agent.spawn_command(cfg.runtime.work_dir),
         prompt_arg_template=profile.agent.prompt_arg_template,
         prompt=prompt,
         prompt_delivery=profile.agent.prompt_delivery,

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/agent_runner/startup_check.py

@@ -50,13 +50,16 @@ def _check_log_dir(cfg: Config) -> CheckResult:
 def _check_agent_target(agent: AgentConfig, work_dir: Path, name: str) -> CheckResult:
     if not agent.command:
         return CheckResult(name, False, "agent.command is empty", permanent=True)
-    cli = agent.command[0]
+    cli = agent.spawn_command(work_dir)[0]
     # Validate with the exact resolution the spawn uses (agent_runtime owns
     # the model): slash-containing commands resolve against work_dir (the
     # child's cwd); bare names use the CHILD's PATH ([agent.env] may set it).
     resolved = agent_runtime.resolve_exec_target(cli, work_dir, env_path=agent.env.get("PATH"))
     if resolved is None:
         relative = "/" in cli
+        # cli is exec_prefix[0] when a prefix is set (spawn_command splices the
+        # prefix first) -- pointing the fix at agent.command[0] would be wrong.
+        target = "[agent] exec_prefix[0]" if agent.exec_prefix else "agent.command[0]"
         return CheckResult(
             name,
             False,
@@ -68,13 +71,41 @@ def _check_agent_target(agent: AgentConfig, work_dir: Path, name: str) -> CheckR
             how_to_fix=(
                 "fix the path relative to runtime.work_dir, or use an absolute path"
                 if relative
-                else f"install {cli} or set agent.command[0] to its absolute path"
+                else f"install {cli} or set {target} to its absolute path"
             ),
             permanent=True,
         )
     return CheckResult(name, True)
 
 
+def _check_stdin_container_interactive(
+    agent: AgentConfig, work_dir: Path, name: str
+) -> CheckResult:
+    """A stdin-delivery agent whose container run drops stdin (no -i/--interactive)
+    silently hangs until the round-timeout kill -- fail loud at boot instead."""
+    if agent.prompt_delivery != "stdin":
+        return CheckResult(name, True)
+    argv = agent.spawn_command(work_dir)
+    if agent_runtime._detect_container_run(argv) is None:
+        return CheckResult(name, True)
+    # Whether docker forwards stdin depends ONLY on docker's own flags
+    # (exec_prefix) -- agent.command runs INSIDE the container, so an -i/
+    # --interactive there is irrelevant and must not satisfy this check.
+    if agent_runtime._exec_prefix_is_interactive(agent.exec_prefix):
+        return CheckResult(name, True)
+
+    return CheckResult(
+        name,
+        False,
+        reason="stdin prompt delivery into a container, but exec_prefix lacks -i/--interactive",
+        how_to_fix=(
+            'add "-i" to [agent] exec_prefix (docker drops stdin without it '
+            "→ the agent hangs until the round-timeout kill)"
+        ),
+        permanent=True,
+    )
+
+
 def _check_work_dir_is_git(cfg: Config) -> CheckResult:
     from agent_runner.vcs_state import GitTimeout, is_git_repo
 
@@ -194,6 +225,14 @@ def _agent_cli_checks(cfg: Config) -> list[CheckResult]:
         profile = cfg.profile_for(phase)
         name = "agent_cli_in_path" if phase is None else f"agent_cli_in_path:{phase}"
         results.append(_check_agent_target(profile.agent, cfg.runtime.work_dir, name))
+        stdin_name = (
+            "stdin_container_interactive"
+            if phase is None
+            else f"stdin_container_interactive:{phase}"
+        )
+        results.append(
+            _check_stdin_container_interactive(profile.agent, cfg.runtime.work_dir, stdin_name)
+        )
     return results
 
 

cli_agent_runner-0.2.21/deploy/Dockerfile

@@ -0,0 +1,24 @@
+# Template Dockerfile for running the whole unit (supervisor + agent CLI) in
+# one container. This is a recipe to copy and adapt into your own project —
+# see docs/recipes/deploy-all-in-one.md — not a published or maintained image.
+
+FROM python:3.12-slim
+
+# git is required: agent-runner's dirty-tree detection shells out to it.
+RUN apt-get update && apt-get install -y --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip install --no-cache-dir cli-agent-runner
+# Pin a specific release for reproducible builds if you need one, e.g.
+# `cli-agent-runner==X.Y.Z`.
+
+# --- Agent CLI slot -----------------------------------------------------
+# agent-runner is CLI-agnostic and ships none. Install whichever agent you
+# configured in agent-runner.toml here, e.g. (needs a Node base image, or an
+# added Node install step first):
+#   RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+# -------------------------------------------------------------------------
+
+WORKDIR /work
+ENTRYPOINT ["agent-runner"]
+CMD ["serve"]

cli_agent_runner-0.2.21/deploy/docker-compose.yml

@@ -0,0 +1,18 @@
+# Template compose file for the all-in-one deploy recipe — copy alongside
+# Dockerfile into your own project and adapt. See
+# docs/recipes/deploy-all-in-one.md.
+
+services:
+  agent-runner:
+    build: .
+    # Mount your project (it must contain agent-runner.toml at its root,
+    # matching [runtime] work_dir = "." in that file) at /work.
+    volumes:
+      - .:/work
+    working_dir: /work
+    environment:
+      # Value-less: pass through from the host shell. Add whatever your
+      # agent CLI needs the same way.
+      - ANTHROPIC_API_KEY
+    command: ["serve"]
+    restart: unless-stopped

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/docs/README.md

@@ -29,6 +29,8 @@ move it to the doc whose charter it belongs to (see the decision procedure in
 | [long-running-agents.md](long-running-agents.md) | Context-rot essay: fresh eyes, long-lineage runs |
 | [recipes/aider.md](recipes/aider.md) | Per-CLI walkthrough — aider |
 | [recipes/codewhale.md](recipes/codewhale.md) | Per-CLI walkthrough — codewhale |
+| [recipes/container-pi.md](recipes/container-pi.md) | Per-CLI walkthrough — pi (+ kimi/claude/podman deltas) run in a container via `exec_prefix` |
+| [recipes/deploy-all-in-one.md](recipes/deploy-all-in-one.md) | Recipe — supervisor + agent CLI in one container |
 | [recipes/kimi.md](recipes/kimi.md) | Per-CLI walkthrough — Kimi Code CLI + Kimi K3 via the claude preset |
 | [recipes/pi.md](recipes/pi.md) | Per-CLI walkthrough — Pi Coding Agent + Kimi K3 via a Moonshot provider |
 

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/docs/commands.md

@@ -275,7 +275,7 @@ The transforms `migrate` applies (generated from the registry):
 - unknown [schedule] key(s) rejected in 0.2.12; delete them (allowed: ['pause_windows', 'run_windows', 'timezone'])
 - monitor.anomaly_repetitive_threshold > anomaly_repetitive_window: lower the threshold or raise the window so the detector can fire
 - [<table>] given as a scalar, not a table; give it real [table] content (no auto-fix possible)
-- unknown [agent] key(s) rejected in 0.2.13; delete them (allowed: ['command', 'env', 'name', 'prompt_arg_template', 'prompt_delivery'])
+- unknown [agent] key(s) rejected in 0.2.13; delete them (allowed: ['command', 'env', 'exec_prefix', 'name', 'prompt_arg_template', 'prompt_delivery'])
 - unknown [runtime] key(s) rejected in 0.2.13; delete them (allowed: ['disable_pre_round_hooks', 'dry_run', 'fresh_eyes_every_n', 'grace_kill_ignore_patterns', 'log_dir', 'max_grace_after_result_s', 'max_rounds', 'narrative_file', 'restart_delay_s', 'round_log_retention', 'round_timeout_s', 'stop_file', 'substrate_fingerprint_paths', 'transient_error_action', 'work_dir'])
 - unknown [vcs] key(s) rejected in 0.2.13; delete them (allowed: ['dirty_action', 'stash_idempotency_s'])
 - unknown [monitor] key(s) rejected in 0.2.13; delete them (allowed: ['anomaly_repetitive_threshold', 'anomaly_repetitive_window', 'auth_fail_hint', 'auth_fail_patterns', 'auto_stop_on', 'host_health', 'remote_failure_tolerance_s', 'round_progress_interval_s', 'supervisor_stale_threshold_s'])

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.21}/docs/configuration.md

@@ -30,6 +30,7 @@ running with newly-set `dirty_action = "auto_commit"` is undefined).
 | `name` | `str \| None` | None |
 | `env` | `dict[str, str]` | {} |
 | `prompt_delivery` | `Literal['argv', 'stdin']` | 'argv' |
+| `exec_prefix` | `list[str]` | [] |
 
 ### `[runtime]`
 
@@ -311,7 +312,7 @@ sub-tables reject unknown keys: `agent` and `runtime` as noted below, and
 
 | Sub-table | Overrides | Fields accepted |
 |---|---|---|
-| `[phases.<name>.agent]` | `[agent]` | any `[agent]` field; field-merged onto the base `[agent]`, then validated (so the `stdin` + `{prompt}` cross-check runs on the merged result) |
+| `[phases.<name>.agent]` | `[agent]` | any `[agent]` field except `exec_prefix` (base-only, see below); field-merged onto the base `[agent]`, then validated (so the `stdin` + `{prompt}` cross-check runs on the merged result) |
 | `[phases.<name>.runtime]` | `[runtime]` | `round_timeout_s`, `disable_pre_round_hooks` only |
 | `[phases.<name>.schedule]` | `[schedule]` | any `[schedule]` field; **replaces** the global windows wholesale |
 | `[phases.<name>.prompt]` | `[prompt]` | `files` only |
@@ -343,6 +344,9 @@ the base config regardless of phase:
   `[monitor]`, and `[plugins]` — global only.
 - `[prompt]` fields other than `files` (`context_injection_mode`,
   `inject_context`, `concat_separator`, …).
+- **`agent.exec_prefix`** — set once on the base `[agent]` table; it applies to
+  every phase. A `[phases.<name>.agent]` sub-table that sets its own
+  `exec_prefix` is rejected at load.
 
 ### `phase_policy` — `wait` vs `skip`
 

cli_agent_runner-0.2.21/docs/recipes/container-pi.md

@@ -0,0 +1,179 @@
+# Running pi inside a container
+
+This is [pi.md](pi.md)'s agent, run inside a container you supply, via
+`[agent] exec_prefix` (schema: [configuration.md](../configuration.md)).
+`exec_prefix` is an opaque list spliced onto the front of `command` at spawn —
+so the effective process is `docker run … my-pi-image pi --mode json`, and
+agent-runner watches that `docker run` client as an ordinary process, exactly
+as it would watch a bare `pi` process. The container (and the OS underneath
+it) enforces the isolation; agent-runner does not sandbox the agent itself —
+it runs the agent in a container you supply and watches from outside.
+
+## Prerequisites
+
+- Docker (or Podman — see the rootless delta below) installed on the
+  supervisor host.
+- Your user in the `docker` group — **not** `sudo` (see Footguns).
+- An image you build yourself, e.g.:
+  ```dockerfile
+  FROM node:20-slim
+  RUN npm i -g --ignore-scripts @earendil-works/pi-coding-agent
+  # the template runs as -u 1000:1000 with HOME=/home/agent, so the image
+  # must provide that dir owned by the UID (or $HOME-relative writes fail):
+  RUN mkdir -p /home/agent && chown 1000:1000 /home/agent
+  ```
+- A provider/model configured for pi — same as [pi.md](pi.md)'s Provider auth
+  section.
+- A git repo as `work_dir`, bind-mounted into the container at `/work`.
+
+## Config
+
+```toml
+[agent]
+command = ["pi", "--mode", "json"]
+exec_prefix = ["docker", "run", "--rm", "-i", "--init", "--stop-timeout", "5",
+               "-u", "1000:1000", "-e", "HOME=/home/agent",
+               "-v", "{work_dir}:/work:Z", "-w", "/work",
+               "-e", "ANTHROPIC_API_KEY", "my-pi-image"]
+```
+
+`{work_dir}` is the one templated token — agent-runner substitutes it with
+the run's absolute `work_dir` at spawn; every other token passes through
+untouched. `command` stays `["pi", "--mode", "json"]`, so pi's identity
+(throttle / crash-loop / usage-plugin keying, all keyed on `command[0]`) is
+unaffected by running inside docker.
+
+### Why each flag
+
+- **`--rm`** — remove the container on exit. Without it, containers
+  accumulate one per round.
+- **`-i`** — keep stdin open. pi's `prompt_delivery = "stdin"` needs it;
+  without `-i`, docker drops stdin and the agent hangs until
+  `round_timeout_s` kills it. agent-runner checks this at startup and
+  refuses to start a stdin-delivery config whose `exec_prefix` is missing
+  `-i`.
+- **`--init`** — run an init process as PID 1 inside the container, so
+  SIGTERM reaches pi and in-container zombies get reaped. Without it, a
+  shell-form entrypoint as PID 1 can ignore SIGTERM outright.
+- **`--stop-timeout 5`** — bound `docker stop`'s grace period so teardown
+  after a stop stays short and predictable.
+- **`-u 1000:1000`** — run as your host UID, not root. A root-owned file
+  written into the bind-mounted `work_dir` poisons agent-runner's host-side
+  dirty-tree stash/commit, and trips git's "dubious ownership" check
+  in-container. Use `id -u`/`id -g` if your UID isn't 1000.
+- **`-e HOME=/home/agent`** — an arbitrary UID has no `/etc/passwd` entry, so
+  `~` expansion breaks inside the container; set `HOME` explicitly.
+- **`-v {work_dir}:/work:Z`** — bind-mount the run's `work_dir`. `:Z`
+  relabels the mount for SELinux hosts (Fedora/RHEL); drop it elsewhere.
+- **`-w /work`** — pi has no `--cwd` flag (see [pi.md](pi.md)), so the
+  container's working directory has to already be the mount.
+- **`-e ANTHROPIC_API_KEY`** (value-less) — forwards the key from
+  agent-runner's own environment into the container. **Never write
+  `-e ANTHROPIC_API_KEY=sk-…`** — a valued `-e` puts the secret straight into
+  the `docker run` argv, which lands in `ps` output and `/proc/<pid>/cmdline`
+  for any local user to read. Add every other provider key the same,
+  value-less way.
+- **`my-pi-image`** — the image you built above.
+
+## Auth
+
+Prefer env vars, as above — there's no state to lose when `--rm` removes the
+container each round. If your provider needs a credential *file* (e.g.
+`pi /login`'s `~/.pi/agent/auth.json`), mount it **outside** `work_dir` —
+mounting it inside would show up as tracked-file churn to agent-runner's
+dirty-tree detector every round:
+
+```
+-v /home/you/.pi-container-auth:/home/agent/.pi/agent:ro
+```
+
+## Footguns
+
+These aren't enforced by agent-runner (`exec_prefix` is opaque) — get them
+right yourself:
+
+- **`sudo docker run` loses the clean stop.** agent-runner's container-orphan
+  defense only injects a `--cidfile` (and so can attempt a clean `docker
+  stop` on a stuck round) for the literal `docker run …` shape. A
+  `sudo`-wrapped or globally-flagged form is still *detected* — you get the
+  warning and event — but not covered by the clean stop. Put your user in
+  the `docker` group instead of prefixing `sudo`.
+- **Missing `--rm`** accumulates one container per round, forever.
+- **`--network none`** breaks the agent outright — it can't reach the model
+  API.
+- **Missing `-u`** runs the container as root — see the root-owned-files
+  footgun above.
+- **`-d`/`--detach`** — never use it. Detached `docker run` exits 0
+  immediately while the container is still starting, so agent-runner sees an
+  instant "successful" round with no agent work actually done.
+- **`-t` without a real TTY** fails fast — docker allocates a pseudo-TTY and
+  errors when the supervisor's own stdin/stdout aren't one, which under a
+  service manager they usually aren't.
+- **`--sig-proxy=false`** disables the relay of agent-runner's SIGTERM into
+  the container for cooperative shutdown. Leave it at its default (`true`).
+
+## Monitoring
+
+`agent_process_count` in `peek`/metrics reads `0` for a containerized round —
+expected, not a failure. The host-side probe counts processes named after the
+agent (`pi`), but the host process is `docker`/`podman`; the agent runs in the
+container's own PID namespace where the probe can't see it. Round liveness is
+tracked by the container process agent-runner supervises directly, not this
+count.
+
+## Not for tiny edge hosts
+
+This recipe assumes a host with room for a container runtime on top of the
+agent's own (non-trivial) memory footprint. It isn't a fit for a small edge
+board — run pi bare there instead (see [pi.md](pi.md)).
+
+## Deltas
+
+### kimi — ENV-only, no mount
+
+[kimi.md](kimi.md)'s CLI is fully configured over four env vars and needs no
+file at all — prefer this shape whenever your CLI supports it, since there's
+nothing to bind-mount:
+
+```toml
+[agent]
+command = ["kimi", "--output-format", "stream-json"]
+exec_prefix = ["docker", "run", "--rm", "-i", "--init", "--stop-timeout", "5",
+               "-u", "1000:1000", "-e", "HOME=/home/agent",
+               "-v", "{work_dir}:/work:Z", "-w", "/work",
+               "-e", "KIMI_MODEL_NAME", "-e", "KIMI_MODEL_API_KEY",
+               "-e", "KIMI_MODEL_BASE_URL", "-e", "KIMI_MODEL_PROVIDER_TYPE",
+               "my-kimi-image"]
+```
+
+### claude — root rejection + config mount
+
+Claude Code refuses `--dangerously-skip-permissions` when run as root, so
+`-u` is mandatory here, not just recommended. If you authenticate via
+`~/.claude` instead of an API key, mount it outside `work_dir` and point
+`CLAUDE_CONFIG_DIR` at the mount:
+
+```toml
+exec_prefix = ["docker", "run", "--rm", "-i", "--init", "--stop-timeout", "5",
+               "-u", "1000:1000", "-e", "HOME=/home/agent",
+               "-v", "{work_dir}:/work:Z", "-w", "/work",
+               "-v", "/home/you/.claude-container:/home/agent/.claude:ro",
+               "-e", "CLAUDE_CONFIG_DIR=/home/agent/.claude",
+               "my-claude-image"]
+```
+
+### rootless podman — `--userns=keep-id` instead of `-u`
+
+Podman rootless already runs as your user; swap `-u 1000:1000` for
+`--userns=keep-id`, which maps your host UID inside the container without
+needing root at all:
+
+```toml
+exec_prefix = ["podman", "run", "--rm", "-i", "--init", "--stop-timeout", "5",
+               "--userns=keep-id", "-e", "HOME=/home/agent",
+               "-v", "{work_dir}:/work:Z", "-w", "/work",
+               "-e", "ANTHROPIC_API_KEY", "my-pi-image"]
+```
+
+See also: [docs/configuration.md](../configuration.md),
+[SECURITY.md](../../SECURITY.md#containment).

cli_agent_runner-0.2.21/docs/recipes/deploy-all-in-one.md

@@ -0,0 +1,49 @@
+# Running the whole unit in one container
+
+This is a **recipe** — `deploy/Dockerfile` and `deploy/docker-compose.yml`
+are templates to copy and adapt into your own project, not a published or
+maintained image.
+
+Where [container-pi.md](container-pi.md) boxes the *agent* and keeps the
+supervisor on the host, this recipe does the opposite: the supervisor and
+the agent CLI both run inside one container, and that container is the unit
+you bound against the host (filesystem, network, resources). agent-runner
+still supervises the agent CLI as an ordinary in-container subprocess — this
+container doesn't add any isolation between the supervisor and the agent, it
+only bounds the whole unit against the host it runs on.
+
+## When to use this vs `exec_prefix`
+
+- **`exec_prefix`** ([container-pi.md](container-pi.md)) — box the agent
+  only; the supervisor keeps its normal host-level view (events, `peek`,
+  host PSI/memory signals). Prefer this by default.
+- **This recipe** — you want one image that *is* the deployable unit (e.g.
+  shipping the whole thing to a host you don't otherwise manage). In
+  exchange, the supervisor's view of memory/PSI pressure is now the
+  container's own, not the host's.
+
+## Files
+
+- `deploy/Dockerfile` — `python:3.12-slim` + `pip install cli-agent-runner` +
+  a commented-out slot for your agent CLI's install step.
+- `deploy/docker-compose.yml` — builds the image, mounts your project (which
+  should contain `agent-runner.toml`) at `/work`, runs `serve`.
+
+## Use it
+
+```bash
+cp deploy/Dockerfile deploy/docker-compose.yml your-project/
+cd your-project
+# edit Dockerfile: uncomment/add your agent CLI's install step
+# agent-runner.toml already exists at the project root (agent-runner init)
+docker compose up -d
+docker compose logs -f
+```
+
+## Not for tiny edge hosts
+
+Same caveat as [container-pi.md](container-pi.md): don't reach for this on a
+small edge board. It's a fat-host/homelab/server recipe.
+
+See also: [docs/quickstart.md](../quickstart.md),
+[SECURITY.md](../../SECURITY.md#containment).