Container Execution

Use this page when a repo already has a Dockerfile and you need to decide how ota fits around it.

Choose this when you want the image build and the readiness contract to stay in separate layers so each one stays honest.

• Dockerfile builds the image
• ota.yaml declares what the repo needs
• ota run and ota up execute against the declared environment
• when legacy execution.preferred: container is set, or when a selected execution context uses backend: container, ota runs inside that image instead of on the host
• if the image comes from a Dockerfile, the Dockerfile is what made the container runnable
• the contract still matters even when the image already exists

• Docker is optional, not a universal prerequisite for ota
• use container mode when the repo or org already allows it
• host bootstrap for Docker is a separate concern and should not be assumed by default
• container mode primarily governs workload execution; topology-aware service reachability now comes from execution contexts plus services.endpoints and services.readiness, not from assuming host and container see the same service surface.
• use tasks.<name>.runtime.listeners when the app itself should stay in the container but still publish a deterministic host URL for browsers, curl, or local tooling

• Dockerfile handles OS packages, runtimes, and reproducible image setup
• ota handles tasks, checks, safe AI-agent guidance, provisioning policy, and execution mode
• container mode gives ota a repeatable runtime boundary for run and up
• workload listeners let ota report the resolved published URL for long-running app tasks instead of making users guess the host port
• doctor still explains whether the repo is ready inside that boundary
• ota doctor --mode container and ota up --mode container target the container image directly
• explicit container mode stops before any host provisioning fallback when the image cannot satisfy declared pins or no supported container engine is available
• if the selected image cannot be pulled or started, ota doctor --container reports that image acquisition blocker before reporting runtime or tool probes inside the image
• use both when the repo already ships a Dockerfile and still needs explicit readiness rules

• use the Dockerfile to make the image runnable
• use the ota contract to make the repo explainable, diagnosable, and safe
• use container mode when you want ota to run against the image instead of the host
• use ota up --dry-run --mode container when you want the exact container preparation plan before ota mutates anything
• use ota up --mode container when you want ota to prepare the repo inside that image before running tasks
• do not replace the contract with the Dockerfile, because the Dockerfile does not tell ota what is safe to run or what should be provisioned
• do not make Docker the default adoption requirement unless the repo or org already uses it

The preview should read like a real operator plan, not a second generic explanation layer.

🦦 UP PREVIEW ./ota.yaml ➤ NOT READY ❖ Mode: dry-run (no write) Execution→ Backend: container→ Lifecycle: persistent→ Image: `eclipse-temurin:21-jdk`→ Task: `setup` Contract→ Project: java-service→ Version: 1→ Execution: preferred=container, lifecycle=persistent, image=eclipse-temurin:21-jdk→ Counts: runtimes=1, tools=1, env=0, services=0, checks=0, tasks=2 Plan→ provision `java` `21` via `sdkman`→ run task `setup`→ re-check repo readiness ➤ Primary BlockerMissing runtime: javaWhy: java is declared in the contract but is not available inside the configured »  Image: `eclipse-temurin:21-jdk`Next: update `execution.backends.container.image` so `java` is available, then rerun `ota up --dry-run --mode container`