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 inherited the generic node:22-slim tag. That tag did not make Debian the explicit supported base and left the images on the older Bookworm release. None of the built-in images installed Podman, so tasks that need to inspect or build OCI images first had to modify the bottle or could not run at all.

Goals / success criteria

• Every Dockerfile under bot_bottle/contrib/*/Dockerfile explicitly inherits debian:trixie-slim, Debian 13 (the current stable release).
• Every image explicitly creates the non-root node runtime user with UID and GID 1000 instead of relying on a language image to provide it.
• 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 debian:trixie-slim base. Install Node.js and npm from Debian stable where a provider needs them, and create the common node runtime user explicitly. 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 Node.js and Podman stability and update channel; this keeps the images distribution-first and avoids adding a third-party package repository.