Problem
claw up currently chooses the injected cllama image exclusively from the compiled infrastructure release manifest and publishes its dashboard port exclusively from the host process CLLAMA_UI_PORT environment variable. Neither value can be represented in claw-pod.yml. A regenerated compose.generated.yml therefore discards any reviewed image override and silently returns to host port 8181, which can collide with another service.
Generated Compose is intentionally not a source artifact, so hand-editing it is not a durable operator contract. Requiring an exported environment variable also makes the pod declaration incomplete and easy to regenerate incorrectly.
Proposed contract
Extend pod-level x-claw.cllama-defaults with explicit runtime fields:
x-claw:
cllama-defaults:
proxy: passthrough
image: ghcr.io/mostlydev/cllama:v0.10.0
dashboard-port: 8281
image overrides the release-manifest image for the selected proxy. It must be a non-empty explicit image reference.
dashboard-port publishes that host port to cllama container port 8081 and must pass the same numeric host-port validation as other generated surfaces.
- The declaration is pod-scoped because one injected proxy is shared by all cllama-enabled services.
- Existing pods remain unchanged: omitted image uses the compiled release pin; omitted dashboard port preserves the current
CLLAMA_UI_PORT/8181 fallback during compatibility migration.
- A service-level declaration should fail closed rather than imply per-agent proxy settings that the runtime cannot honor.
Acceptance
- Parser tests cover both fields, invalid/empty forms, and the pod-only boundary.
- Compose tests prove the declared image and
<host>:8081 mapping.
claw pull / missing-image preflight recognize the declared override rather than insisting on the release-manifest image.
- User docs describe the declarative source of truth and generated Compose remains disposable.
- Existing unit and integration suites pass.
This is a general operator reproducibility defect; no downstream deployment details belong in public artifacts.
Problem
claw upcurrently chooses the injected cllama image exclusively from the compiled infrastructure release manifest and publishes its dashboard port exclusively from the host processCLLAMA_UI_PORTenvironment variable. Neither value can be represented inclaw-pod.yml. A regeneratedcompose.generated.ymltherefore discards any reviewed image override and silently returns to host port 8181, which can collide with another service.Generated Compose is intentionally not a source artifact, so hand-editing it is not a durable operator contract. Requiring an exported environment variable also makes the pod declaration incomplete and easy to regenerate incorrectly.
Proposed contract
Extend pod-level
x-claw.cllama-defaultswith explicit runtime fields:imageoverrides the release-manifest image for the selected proxy. It must be a non-empty explicit image reference.dashboard-portpublishes that host port to cllama container port 8081 and must pass the same numeric host-port validation as other generated surfaces.CLLAMA_UI_PORT/8181 fallback during compatibility migration.Acceptance
<host>:8081mapping.claw pull/ missing-image preflight recognize the declared override rather than insisting on the release-manifest image.This is a general operator reproducibility defect; no downstream deployment details belong in public artifacts.