bot-bottle/docs/prds/0026-agent-provider-templates.md

PRD 0026: Agent Provider Templates

• Status: Active
• Author: codex
• Created: 2026-05-28

Summary

Support Claude and Codex agent providers while keeping agent files provider-agnostic and bottle files responsible for boundaries.

Problem

Today bot-bottle is hard-wired around Claude Code assumptions. When Claude runs out or is otherwise unavailable, the operator cannot spin up an equivalent Codex-backed bottle from the dashboard or start path. Agent files should remain purpose/guidance documents, while bottle files define security boundaries and provider/runtime choices.

Goals / Success Criteria

• A Codex agent can be started from the dashboard and via ./cli.py start alongside a Claude agent.
• The manifest can express the agent provider/template and, where needed, a custom agent Dockerfile.
• Claude-specific default egress/auth behavior is no longer implicit; provider-specific auth is expressed through explicit bottle egress routes and roles.
• The launcher preserves required infrastructure behavior for sidecars, egress, pipelock, supervisor MCP, CA handling, git, and shell basics.
• Unit tests cover manifest parsing, provider validation, provider-specific auth role behavior, and launch/prepare plan differences.

Non-goals

• Do not implement support for providers beyond Claude and Codex.
• Do not move security boundaries into agent files.
• Do not allow custom Dockerfiles to remove or bypass required bot-bottle infrastructure.
• Do not add new runtime dependencies unless the existing Docker/Codex tooling cannot satisfy the minimum cut.

Scope

In scope

• Add a bottle-level provider/template configuration for Claude and Codex.
• Add a Codex template that can launch a Codex agent from the dashboard and start.
• Support a custom agent Dockerfile path for the agent environment.
• Make Claude-specific egress/auth defaults explicit in bottle manifests instead of auto-provided.
• Add a Codex-specific auth role and provider-aware role validation.
• Keep existing Claude behavior available through a Claude provider/template.
• Gate Claude-specific crash-state/transcript handling behind a Claude-only flag or provider branch.

Out of scope

• Implementing providers beyond Claude and Codex.
• Redesigning the agent file format beyond keeping it provider/bottle agnostic.
• Reworking the whole state/transcript subsystem in this PRD; provider-specific state handling should be isolated now and refactored in a follow-up.

Proposed Design

New services / components

• New AgentProvider model for provider/template behavior.
• Bottle manifests use a nested agent_provider shape:

agent_provider:
  template: codex    # or claude
  dockerfile: ./Dockerfile.codex  # optional

• Provider templates do not implicitly add egress routes. Operators should put provider-specific agent_provider and egress/auth routes in home-owned base bottles such as claude or codex, then use extends for task-specific bottles.
• Provider-specific launch configuration for Claude and Codex, including command argv, auth placeholder behavior, and default image/Dockerfile selection.
• Provider-aware egress role validation, including a new Codex auth role.

Existing code touched

• bot_bottle/manifest.py for provider schema and role validation.
• Docker and smolmachines prepare/launch/provision paths for provider-specific image, command, auth, and state behavior.
• Dashboard/start display paths so the selected provider is visible and usable.
• README and PRD docs for provider/template configuration.
• Unit tests around manifest parsing, backend plans, launch argv, egress roles, and dashboard/start behavior.

Data model changes

• Manifest schema gains bottle-level provider/template configuration.
• No persistent state migration is expected.
• Existing Claude-specific crash-state/transcript dumping in the state folder should be guarded so it only runs for Claude agents. A broader state/transcript abstraction is a follow-up.

External dependencies

• Avoid new runtime dependencies where possible.
• Use existing Docker image build flows and whatever Codex install is already available in the chosen agent image/template.

Open questions

• codex_auth is retained as a placeholder marker for follow-up Codex credential-injection work. The Codex template should not inject an OPENAI_API_KEY placeholder; Codex bottles use device/ChatGPT login state instead.
• Existing state-folder transcript capture is Claude-specific and should remain gated to Claude until the follow-up state/transcript refactor.

References

• Issue #90: Support for different agents