feat(agent): add provider templates

Assisted-by: Codex

claude_bottle/backend/__init__.py

@@ -215,6 +215,7 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
         bottle = manifest.bottle_for(spec.agent_name)
         self._validate_skills(agent.skills)
         self._validate_git_entries(bottle.git)
+        self._validate_agent_provider_dockerfile(spec)
 
     def _validate_skills(self, skills: Sequence[str]) -> None:
         """Each named skill must be a directory under the host's
@@ -238,6 +239,20 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
             if not os.path.isfile(key):
                 die(f"git upstream key file not found for '{entry.Name}': {key}")
 
+    def _validate_agent_provider_dockerfile(self, spec: BottleSpec) -> None:
+        bottle = spec.manifest.bottle_for(spec.agent_name)
+        dockerfile = bottle.agent_provider.dockerfile
+        if not dockerfile:
+            return
+        path = Path(expand_tilde(dockerfile))
+        if not path.is_absolute():
+            path = Path(spec.user_cwd) / path
+        if not path.is_file():
+            die(
+                f"agent_provider.dockerfile for bottle "
+                f"'{spec.manifest.agents[spec.agent_name].bottle}' not found: {path}"
+            )
+
     @abstractmethod
     def _resolve_plan(self, spec: BottleSpec, *, stage_dir: Path) -> PlanT:
         """Backend-specific plan resolution: image/container names,

claude_bottle/backend/docker/bottle.py

@@ -1,16 +1,11 @@
-"""DockerBottle — concrete Bottle handle yielded by
-DockerBottleBackend.launch.
-
-Holds the container name plus the in-container prompt path so
-exec_claude can transparently add --append-system-prompt-file when a
-prompt was provisioned.
-"""
+"""DockerBottle — concrete Bottle handle yielded by DockerBottleBackend."""
 
 from __future__ import annotations
 
 import subprocess
 from typing import Callable
 
+from ...agent_provider import prompt_args
 from .. import Bottle, ExecResult
 
 
@@ -22,22 +17,32 @@ class DockerBottle(Bottle):
         container: str,
         teardown: Callable[[], None],
         prompt_path_in_container: str | None,
+        *,
+        agent_command: str = "claude",
+        agent_prompt_mode: str = "claude_append_file",
     ):
         self.name = container
         self._teardown = teardown
         self._prompt_path = prompt_path_in_container
+        self._agent_command = agent_command
+        self._agent_prompt_mode = agent_prompt_mode
+        self.agent_command = agent_command
+        self.agent_provider_template = (
+            "codex" if agent_command == "codex" else "claude"
+        )
         self._closed = False
 
     def claude_argv(
         self, argv: list[str], *, tty: bool = True,
     ) -> list[str]:
         full_argv = list(argv)
-        if self._prompt_path:
-            full_argv.extend(["--append-system-prompt-file", self._prompt_path])
+        full_argv.extend(
+            prompt_args(self._agent_prompt_mode, self._prompt_path, argv=full_argv)
+        )
         cmd = ["docker", "exec"]
         if tty:
             cmd.append("-it")
-        cmd.extend([self.name, "claude", *full_argv])
+        cmd.extend([self.name, self._agent_command, *full_argv])
         return cmd
 
     def exec_claude(self, argv: list[str], *, tty: bool = True) -> int:

claude_bottle/backend/docker/bottle_plan.py

@@ -51,6 +51,9 @@ class DockerBottlePlan(BottlePlan):
     # is opt-in via the manifest's bottle.supervise field.
     supervise_plan: SupervisePlan | None
     use_runsc: bool
+    agent_command: str = "claude"
+    agent_prompt_mode: str = "claude_append_file"
+    agent_provider_template: str = "claude"
 
     def print(self, *, remote_control: bool) -> None:
         """Render the y/N preflight summary to stderr — compact form
@@ -73,6 +76,7 @@ class DockerBottlePlan(BottlePlan):
 
         print(file=sys.stderr)
         info(f"agent           : {spec.agent_name}")
+        info(f"provider        : {self.agent_provider_template}")
         print_multi("env             ", env_names)
         print_multi("skills          ", list(agent.skills))
         info(f"bottle          : {agent.bottle}")
@@ -91,4 +95,3 @@ class DockerBottlePlan(BottlePlan):
                 egress_lines.append(f"{r.host}{auth}")
             print_multi("  egress        ", egress_lines)
         print(file=sys.stderr)
-

claude_bottle/backend/docker/launch.py

@@ -207,6 +207,12 @@ def launch(
         # Step 9: yield. exec_claude continues to use `docker exec -it`
         # — the agent runs `sleep infinity` per the renderer's
         # service spec.
-        yield DockerBottle(plan.container_name, teardown, prompt_path)
+        yield DockerBottle(
+            plan.container_name,
+            teardown,
+            prompt_path,
+            agent_command=plan.agent_command,
+            agent_prompt_mode=plan.agent_prompt_mode,
+        )
     finally:
         teardown()

claude_bottle/backend/docker/prepare.py

@@ -14,6 +14,7 @@ import os
 from datetime import datetime, timezone
 from pathlib import Path
 
+from ...agent_provider import runtime_for
 from ...egress import Egress
 from ...env import ResolvedEnv, resolve_env
 from ...git_gate import GitGate
@@ -58,6 +59,8 @@ def resolve_plan(
     manifest = spec.manifest
     agent = manifest.agents[spec.agent_name]
     bottle = manifest.bottle_for(spec.agent_name)
+    provider = bottle.agent_provider
+    provider_runtime = runtime_for(provider.template)
 
     # PRD 0016 follow-up: identity, not bare slug. A fresh `start`
     # mints a random-suffixed identity (so parallel runs of the same
@@ -89,8 +92,14 @@ def resolve_plan(
     if per_bottle_dockerfile(slug) is not None:
         image_default = per_bottle_image_tag(slug)
         dockerfile_path = str(per_bottle_dockerfile_path(slug))
+    elif provider.dockerfile:
+        image_default = f"claude-bottle:{provider.template}-{slug}"
+        dockerfile_path = _resolve_manifest_dockerfile(provider.dockerfile, spec)
+    elif provider_runtime.dockerfile:
+        image_default = provider_runtime.image
+        dockerfile_path = provider_runtime.dockerfile
     else:
-        image_default = "claude-bottle:latest"
+        image_default = provider_runtime.image
     image = os.environ.get("CLAUDE_BOTTLE_IMAGE", image_default)
     derived_image = ""
     runtime_image = image
@@ -171,8 +180,16 @@ def resolve_plan(
         # PRD 0017 chunk 3 moved them behind the
         # `list-egress-routes` MCP tool so the agent gets live
         # state rather than a launch-time snapshot.)
-        dockerfile_path = Path(__file__).resolve().parent.parent.parent.parent / "Dockerfile"
-        dockerfile_content = dockerfile_path.read_text() if dockerfile_path.is_file() else ""
+        supervise_dockerfile_path = (
+            Path(dockerfile_path)
+            if dockerfile_path
+            else Path(__file__).resolve().parent.parent.parent.parent / "Dockerfile"
+        )
+        dockerfile_content = (
+            supervise_dockerfile_path.read_text()
+            if supervise_dockerfile_path.is_file()
+            else ""
+        )
         supervise_dir = supervise_state_dir(slug)
         supervise_dir.mkdir(parents=True, exist_ok=True)
         supervise_plan = supervise.prepare(
@@ -192,12 +209,12 @@ def resolve_plan(
     # placeholder. The placeholder isn't any real token value, so
     # leaking it would tell an attacker only that egress is in
     # front. Manifest validation enforces singleton on this role.
-    has_anthropic_auth = any(
-        "claude_code_oauth" in r.roles
-        for r in egress_plan.routes
+    has_provider_auth = any(
+        provider_runtime.auth_role in r.roles for r in egress_plan.routes
     )
-    if has_anthropic_auth:
-        forwarded_env["CLAUDE_CODE_OAUTH_TOKEN"] = "egress-placeholder"
+    if has_provider_auth:
+        forwarded_env[provider_runtime.placeholder_env] = "egress-placeholder"
+    if provider.template == "claude" and has_provider_auth:
         # Belt-and-braces: turn off telemetry endpoints (statsig,
         # error reporting) that egress can't gate by auth.
         forwarded_env.setdefault("CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "1")
@@ -225,6 +242,9 @@ def resolve_plan(
         egress_plan=egress_plan,
         supervise_plan=supervise_plan,
         use_runsc=use_runsc,
+        agent_command=provider_runtime.command,
+        agent_prompt_mode=provider_runtime.prompt_mode,
+        agent_provider_template=provider.template,
     )
 
 
@@ -243,3 +263,10 @@ def _write_env_file(resolved: ResolvedEnv, env_file: Path) -> None:
         env_lines.append(f"{name}={value}")
     env_file.write_text("\n".join(env_lines) + ("\n" if env_lines else ""))
     env_file.chmod(0o600)
+
+
+def _resolve_manifest_dockerfile(path_value: str, spec: BottleSpec) -> str:
+    path = Path(os.path.expanduser(path_value))
+    if not path.is_absolute():
+        path = Path(spec.user_cwd) / path
+    return str(path)

claude_bottle/backend/smolmachines/bottle.py

@@ -21,6 +21,7 @@ import subprocess
 import sys
 from typing import Mapping
 
+from ...agent_provider import prompt_args
 from .. import Bottle, ExecResult
 from . import pty_resize as _pty_resize
 from . import smolvm as _smolvm
@@ -72,6 +73,8 @@ class SmolmachinesBottle(Bottle):
         *,
         prompt_path: str | None = None,
         guest_env: Mapping[str, str] | None = None,
+        agent_command: str = "claude",
+        agent_prompt_mode: str = "claude_append_file",
     ) -> None:
         self.name = machine_name
         # In-VM path to the agent's prompt file. None when the
@@ -83,6 +86,12 @@ class SmolmachinesBottle(Bottle):
         # Forwarded on every `smolvm machine exec` via `-e K=V`
         # because exec doesn't inherit from machine_create's env.
         self._guest_env = dict(guest_env or {})
+        self._agent_command = agent_command
+        self._agent_prompt_mode = agent_prompt_mode
+        self.agent_command = agent_command
+        self.agent_provider_template = (
+            "codex" if agent_command == "codex" else "claude"
+        )
 
     def claude_argv(
         self, argv: list[str], *, tty: bool = True,
@@ -92,10 +101,16 @@ class SmolmachinesBottle(Bottle):
             flags += ["-i", "-t"]
         flags += _env_flags_for("node")
         flags += _guest_env_flags(self._guest_env)
-        claude_tail = ["claude"]
-        if self._prompt_path:
-            claude_tail += ["--append-system-prompt-file", self._prompt_path]
-        claude_tail += argv
+        claude_tail = [self._agent_command]
+        provider_prompt_args = prompt_args(
+            self._agent_prompt_mode, self._prompt_path, argv=argv,
+        )
+        if self._agent_prompt_mode == "codex_read_prompt_file":
+            claude_tail += argv
+            claude_tail += provider_prompt_args
+        else:
+            claude_tail += provider_prompt_args
+            claude_tail += argv
         flags += ["--", "runuser", "-u", "node", "--", *claude_tail]
         if not tty:
             # No PTY allocated — no SIGWINCH to forward, no resize

claude_bottle/backend/smolmachines/bottle_plan.py

@@ -92,6 +92,10 @@ class SmolmachinesBottlePlan(BottlePlan):
     agent_proxy_url: str = ""
     agent_git_gate_host: str = ""
     agent_supervise_url: str = ""
+    agent_command: str = "claude"
+    agent_prompt_mode: str = "claude_append_file"
+    agent_provider_template: str = "claude"
+    agent_dockerfile_path: str = ""
 
     def print(self, *, remote_control: bool) -> None:
         """Compact y/N preflight. Same shape as the Docker
@@ -113,6 +117,7 @@ class SmolmachinesBottlePlan(BottlePlan):
 
         print(file=sys.stderr)
         info(f"agent           : {spec.agent_name}")
+        info(f"provider        : {self.agent_provider_template}")
         print_multi("env             ", env_names)
         print_multi("skills          ", list(agent.skills))
         info(f"bottle          : {agent.bottle}")

claude_bottle/backend/smolmachines/launch.py

@@ -219,7 +219,10 @@ def launch(
         # output doesn't garble the dashboard's preflight modal:
         # both the curses-endwin path and the tmux pane-routing
         # path redirect stderr around `launch` already.
-        agent_from_path = _ensure_smolmachine(plan.agent_image_ref)
+        agent_from_path = _ensure_smolmachine(
+            plan.agent_image_ref,
+            dockerfile=plan.agent_dockerfile_path,
+        )
 
         # smolvm VM. --from carries the pre-packed .smolmachine
         # artifact; --allow-cidr + -e carry the per-bottle TSI
@@ -286,6 +289,8 @@ def launch(
             plan.machine_name,
             prompt_path=prompt_path,
             guest_env=plan.guest_env,
+            agent_command=plan.agent_command,
+            agent_prompt_mode=plan.agent_prompt_mode,
         )
     finally:
         stack.close()
@@ -413,7 +418,7 @@ def _resolve_token_env(
     return egress_resolve_token_values(ep.token_env_map, dict(host_env))
 
 
-def _ensure_smolmachine(image_ref: str) -> Path:
+def _ensure_smolmachine(image_ref: str, *, dockerfile: str = "") -> Path:
     """Build the agent docker image and convert it into a
     `.smolmachine` artifact, caching the result under
     `~/.cache/claude-bottle/smolmachines/` keyed by the docker image
@@ -438,7 +443,7 @@ def _ensure_smolmachine(image_ref: str) -> Path:
     so we skip the whole pipeline when the cached sidecar is
     already on disk for this image ID."""
     _SMOLMACHINE_CACHE_DIR.mkdir(parents=True, exist_ok=True)
-    docker_mod.build_image(image_ref, _REPO_DIR)
+    docker_mod.build_image(image_ref, _REPO_DIR, dockerfile=dockerfile)
     # `sha256:abcd...` -> `abcd...` first 16 chars: short enough to
     # keep filenames manageable, long enough to make collisions
     # astronomically unlikely.

claude_bottle/backend/smolmachines/prepare.py

@@ -14,6 +14,7 @@ import os
 from datetime import datetime, timezone
 from pathlib import Path
 
+from ...agent_provider import runtime_for
 from ...backend import BottleSpec
 from ...backend.docker.bottle_state import (
     BottleMetadata,
@@ -55,6 +56,8 @@ def resolve_plan(
 
     manifest = spec.manifest
     bottle = manifest.bottle_for(spec.agent_name)
+    provider = bottle.agent_provider
+    provider_runtime = runtime_for(provider.template)
 
     slug = spec.identity or bottle_identity(spec.agent_name)
 
@@ -117,8 +120,12 @@ def resolve_plan(
     # the agent gets a non-secret placeholder here (matches the
     # docker backend's forwarded_env logic in
     # claude_bottle/backend/docker/prepare.py).
-    if any("claude_code_oauth" in r.roles for r in egress_plan.routes):
-        guest_env["CLAUDE_CODE_OAUTH_TOKEN"] = "egress-placeholder"
+    has_provider_auth = any(
+        provider_runtime.auth_role in r.roles for r in egress_plan.routes
+    )
+    if has_provider_auth:
+        guest_env[provider_runtime.placeholder_env] = "egress-placeholder"
+    if provider.template == "claude" and has_provider_auth:
         guest_env.setdefault("CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "1")
         guest_env.setdefault("DISABLE_ERROR_REPORTING", "1")
 
@@ -145,9 +152,16 @@ def resolve_plan(
     # Stash the agent image ref — `launch.launch` runs the
     # build → pack pipeline at bringup. Honors CLAUDE_BOTTLE_IMAGE
     # to match the docker backend's `resolve_plan` default.
-    agent_image_ref = os.environ.get(
-        "CLAUDE_BOTTLE_IMAGE", "claude-bottle:latest"
-    )
+    agent_dockerfile_path = ""
+    if provider.dockerfile:
+        agent_dockerfile_path = _resolve_manifest_dockerfile(provider.dockerfile, spec)
+        image_default = f"claude-bottle:{provider.template}-{slug}"
+    elif provider_runtime.dockerfile:
+        agent_dockerfile_path = provider_runtime.dockerfile
+        image_default = provider_runtime.image
+    else:
+        image_default = provider_runtime.image
+    agent_image_ref = os.environ.get("CLAUDE_BOTTLE_IMAGE", image_default)
 
     return SmolmachinesBottlePlan(
         spec=spec,
@@ -164,4 +178,15 @@ def resolve_plan(
         git_gate_plan=git_gate_plan,
         egress_plan=egress_plan,
         supervise_plan=supervise_plan,
+        agent_command=provider_runtime.command,
+        agent_prompt_mode=provider_runtime.prompt_mode,
+        agent_provider_template=provider.template,
+        agent_dockerfile_path=agent_dockerfile_path,
     )
+
+
+def _resolve_manifest_dockerfile(path_value: str, spec: BottleSpec) -> str:
+    path = Path(os.path.expanduser(path_value))
+    if not path.is_absolute():
+        path = Path(spec.user_cwd) / path
+    return str(path)