# 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:

```yaml
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