Skip to content

Decision record · ADR

ADR-0052: Let an external image keep its own entrypoint for workload commands

Status: accepted | Date: 2026-09-28

References: RFC-0003, RFC-0002

An external image is a digest-pinned image InferLab did not build. RFC-0003 has required InferLab to replace its entrypoint with the rendered command and to assume nothing about it, because an entrypoint may itself be a fixed serving command that an appended command would corrupt. Some community images instead ship an entrypoint that is the supported way to run anything in them: the reported vLLM image’s lil-entrypoint dispatches every explicit python, bash, or vllm command through its runtime bootstrap, which preloads the image’s NCCL build and selects its CUDA toolkit. Replacing that entrypoint skipped the bootstrap, so the operator copied its exports into extra_env by hand and could not tell whether an engine deadlock came from the image or from the launch difference. The image’s own entrypoint already knows its bootstrap; InferLab does not need to learn it.

An external image definition MAY declare entrypoint = "image". Serving processes and adhoc commands in that image then run without an entrypoint override: InferLab passes the image reference followed by the rendered or operator command, and the image’s own entrypoint receives it as arguments. The default, entrypoint = "replace", keeps today’s explicit override. The choice belongs to the external image definition because it is a fact about how the image is meant to be run, not about a server or machine. InferLab’s own adapter and framework-version probes in the image keep the explicit override: they are InferLab tooling, not workload commands. InferLab still renders the complete engine command, ports, devices, mounts, environment, readiness, and records; the recorded docker command, without --entrypoint, is the evidence of the choice.

Images whose entrypoint wraps explicit commands run under InferLab exactly as their publishers document, without copying bootstrap environment into workspace settings. A managed launch can be compared against the image’s documented launch with only the engine arguments differing. An operator who selects image for an image whose entrypoint does not execute its arguments gets that image’s failure; the default stays safe, and the recorded command shows which path ran. Image-owned opaque launch modes and container ulimit or shared-memory settings remain out of scope until a concrete image needs them.

Let an external image definition opt in to its own entrypoint with entrypoint = "image", defaulting to “replace” (accepted)

Section titled “Let an external image definition opt in to its own entrypoint with entrypoint = "image", defaulting to “replace” (accepted)”
  • Pros: Reuses the image’s own knowledge of its bootstrap; one field, no image paths in the workspace, The rendered engine command, ports, devices, mounts, and records stay InferLab-owned
  • Cons: Selecting it for an image whose entrypoint is a fixed command fails at launch; the default stays safe

Declare a launch prefix on the external image, for example launch_prefix = ["/opt/venv/bin/lil-runtime-bootstrap"], prepended to the rendered command under an explicit entrypoint override (rejected)

Section titled “Declare a launch prefix on the external image, for example launch_prefix = ["/opt/venv/bin/lil-runtime-bootstrap"], prepended to the rendered command under an explicit entrypoint override (rejected)”
  • Pros: Explicit about the wrapper path
  • Cons: Restates the bootstrap path the image’s entrypoint and contract already own, and drifts when the image changes it

Add an image-owned launch mode that runs the image entrypoint with operator arguments and treats the engine as opaque apart from a readiness URL (rejected)

Section titled “Add an image-owned launch mode that runs the image entrypoint with operator arguments and treats the engine as opaque apart from a readiness URL (rejected)”
  • Pros: Benchmarks community images exactly as they ship
  • Cons: Drops integration lowering and the exact rendered command from resolution and records; no concrete image needs it

Keep the explicit override and have operators reproduce the bootstrap through extra_env (rejected)

Section titled “Keep the explicit override and have operators reproduce the bootstrap through extra_env (rejected)”
  • Pros: No InferLab change
  • Cons: Hand-copied environment drifts from the image and cannot prove the launch matches its documented one