bot-bottle/docs/prds/prd-new-modernize-built-in-agent-images.md

PRD prd-new: Modernize built-in agent images

• Status: Draft
• Author: Codex
• Created: 2026-07-21
• Issue: #451

Summary

Keep every built-in agent provider on Debian's current stable release and make Podman available inside each image. This gives agents a consistent, modern userspace and an OCI container tool without requiring per-project setup.

Problem

The Claude, Codex, and Pi images inherit the generic node:22-slim tag. That tag does not state which Debian release the project supports and currently leaves the images on the older Bookworm release. None of the built-in images installs Podman, so tasks that need to inspect or build OCI images must first modify the bottle or cannot run at all.

Goals / success criteria

• Every Dockerfile under bot_bottle/contrib/*/Dockerfile explicitly inherits node:22-trixie-slim, based on Debian 13 (the current stable release).
• Every built-in agent image installs Podman from Debian stable.
• Every built-in agent image retains an SSH client for Git-over-SSH workflows.
• The non-root agent user owns a traversable XDG Git configuration directory, so Git can load bot-bottle's global git-gate rewrites without permission errors.
• A shared test enforces both requirements for current and future built-in providers.

Non-goals

• Configuring privileged or nested-container execution for bottles.
• Pinning Podman outside Debian's stable package repository.
• Changing the Node.js or agent CLI release policy.

Design

Use the explicit node:22-trixie-slim base rather than the floating slim variant. Install the podman package with each image's existing apt-get dependency layer, so package metadata and caches are still removed in the same layer. Treat Debian stable as the Podman stability and update channel; this keeps the images stdlib/distribution-first and avoids adding a third-party package repository.