Skip to content

Decision record · ADR

ADR-0070: Project Pixi manifest activation scripts into the image entrypoint

Status: accepted | Date: 2026-10-28

References: RFC-0007, ADR-0005, RFC-0003

Some activation is a per-host runtime decision. The motivating case prepends a CUDA forward-compatibility library directory to the library path only when the shipped compatibility libcuda is newer than the loaded kernel driver: a host on an older driver needs it, and a host on a newer driver fails CUDA initialization with it. Static activation values cannot express that condition, so a workspace writes it as a Pixi activation script. Host runs already evaluate such a script on each target host, because every host process starts through Pixi. Until RFC-0007 0.5.0, image resolution rejected every composed activation script, so a workspace had to choose between correct host runs and buildable images. Two constraints shape the answer: the Pixi manifest is the single activation authority shared by host and image runs (ADR-0005), and a built image runs through its generated activation entrypoint (RFC-0003:C-RUNTIME-WORKFLOWS). Pixi also executes package-provided conda activate.d scripts, which the image entrypoint never has. An inventory of package activate.d scripts in one production vLLM and SGLang workspace found compiler-toolchain variables (compiler names, compile and link flags, CMake arguments, the nvcc host compiler) and two library catalog paths. Images built without any of them were validated on that workspace’s serving and evaluation recipes, including recipes that JIT-compile kernels. We infer that the compiler names are unneeded at runtime because the environment’s compilers resolve through the projected PATH, and that serving does not consume the flags or catalog paths; other package sets may differ.

We will source the activation scripts the selected Pixi environment composes, with bash and in Pixi’s observed composition order, for every process a built image starts, and then apply projected variables with Pixi’s observed precedence — except that a variable supplied at container start is not overwritten by its projected value and InferLab-managed variables keep InferLab’s values, preserving the runtime-injection precedence of ADR-0005. Package-provided activate.d scripts stay out of the entrypoint. The workspace’s existing scripts become the image’s activation without any new declaration, so host and image runs keep one authority, and the entrypoint stays a generic composition of static projected values and sourced workspace scripts with no knowledge of drivers, CUDA, or any framework. Where scripts are placed in the image and how the assembly-time activation check is realized are left to implementation within RFC-0007:C-IMAGE-BUILD. This replaces the override semantics recorded in ADR-0005’s activation-projection note.

Host-dependent activation behaves the same in host and container runs. An image whose environment composes no script needs no bash and runs no script at start; its runtime activation changes only where the corrected composition affects its variables: activation declared on the environment or under a target selector that was previously omitted, or a projected value that referenced another projected value. Images that project scripts depend on bash and on the scripts’ own runtime tools being present in the base image. The assembly-time activation check fails the build when a script cannot run in the driverless build environment (missing bash or tools, a non-zero exit); it cannot exercise branches that depend on the host driver or GPU, which still fail at launch, where validation is the guard. Script exports during package builds depend on the builder host and are not redirected into the sanitized view, leaving package verification and the mutation audit as the guard. Scripts are committed workspace content copied into a portable artifact, so keeping private facts out of them is the workspace author’s responsibility, bounded by the tracked-file and workspace-root rejections. Package activate.d variables stay absent from images; a workload that needs one at runtime must restate it as a static activation value or reopen this decision with evidence.

Execute the Pixi environment’s composed manifest activation scripts in the generated image entrypoint, with no new declaration (accepted)

Section titled “Execute the Pixi environment’s composed manifest activation scripts in the generated image entrypoint, with no new declaration (accepted)”
  • Pros: One activation authority for host and image runs; existing scripts work unchanged, Generic: the entrypoint knows nothing about drivers or frameworks
  • Cons: Images depend on bash and on scripts being written to run without the workspace tree or a GPU driver, The image’s runtime environment is no longer fully visible from the record; script effects depend on the host and are observed only at start, Images still lack the package activate.d variables that host runs receive

A declarative conditional library-path declaration evaluated by InferLab, such as prepending a directory when its libcuda is newer than the loaded driver (rejected)

Section titled “A declarative conditional library-path declaration evaluated by InferLab, such as prepending a directory when its libcuda is newer than the loaded driver (rejected)”
  • Pros: Statically inspectable; no shell execution at container start
  • Cons: Puts driver-version policy that drifts with CUDA into the framework-neutral control plane, and each further host-dependent need requires another declaration kind, Host runs would still execute the workspace’s script, leaving two authorities for one fact
  • Rejected because: Hardware policy does not belong in the control plane, and a second declaration splits the activation authority the Pixi manifest owns

An image-specific entrypoint hook declared in the image definition, or chaining the base image’s own entrypoint (rejected)

Section titled “An image-specific entrypoint hook declared in the image definition, or chaining the base image’s own entrypoint (rejected)”
  • Pros: Covers container-only start-up needs as well
  • Cons: Host runs never execute it, so the same logic is written twice; base-image entrypoints are opaque content outside the workspace
  • Rejected because: No container-only need has been demonstrated; the demonstrated need is shared host and image activation, which the Pixi manifest already expresses

Also execute package-provided conda activate.d scripts in the entrypoint (rejected)

Section titled “Also execute package-provided conda activate.d scripts in the entrypoint (rejected)”
  • Pros: Closer to Pixi’s full activation
  • Cons: Changes every image’s runtime environment, adding compile and link flags to runtime JIT compilation, for no demonstrated runtime need
  • Rejected because: Validated images already serve without them, the cost falls on every existing image, and the compiler-toolchain variables are build-time needs that package builds still receive through Pixi