Skip to content

Launcher forwarding

This page explains how a generated launcher embeds its package root and how a running ocx forwards its configuration to every ocx it spawns.

Launcher Embedding

ocx package install generates a launcher for each of a package’s declared entry points. Each launcher delegates to the internal ocx launcher exec subcommand, with the package-root path baked in at install time.

Unix (POSIX sh):

launcher
#!/bin/sh
# Generated by ocx at install time. Do not edit.
exec "${OCX_BINARY_PIN:-ocx}" launcher exec '/home/alice/.ocx/packages/ocx.sh/sha256/ab/c123…' -- "${0##*/}" "$@"

Windows (native .exe launcher + .shim sidecar):

# entrypoints/pipx.shim — one UTF-8 line, the absolute package root
C:\Users\alice\.ocx\packages\ocx.sh\sha256\ab\c123…

The accompanying pipx.exe is a compiled launcher. It derives its entry-point name from its own filename and reads pipx.shim for the package root. It then spawns ocx launcher exec "<pkg-root>" -- "pipx" <args…> directly through CreateProcessW — never cmd.exe.

ocx launcher exec forces the private surface internally — no flag needs to be baked into the launcher. The stable wire ABI is the launcher exec subcommand name pair and positional shape.

See the Entry points in-depth page for the full launcher generation pipeline, character rejection rules, and cross-platform launcher behavior.

OCX Configuration Forwarding

Two variables cross into every ocx descendant. __OCX_ENV_STATE is the OCX-only state: a versioned value with a plaintext header and a compressed payload. OCX_BINARY_PIN names the binary that child runs. Together they keep configuration coherent across a chain. One example is ocx package exec running a tool that invokes a generated entry-point launcher. That launcher re-enters OCX.

Carrier Content Purpose
OCX_BINARY_PIN The stable install path when the running OCX is the installed one, else the running binary Pins the inner OCX to a binary that survives an update of the one that installed the package
__OCX_ENV_STATE Header: narrowing policy (n=offline, n=frozen, …) and the home (h=). Payload: applied values, received policy, session selection Child OCX stays offline or frozen if the outer was, and resolves the same home

The root flags --config, --remote, --offline, --frozen and --index reach children through the state. --no-consent reaches them as a narrowing. Subcommand flags such as --no-verify never do.

The resolved [mirrors], [patches], [managed], [records] and toolchain-root settings travel the same way. A launcher re-entry takes no flags of its own. It sees the same mirror map, companion overlay and records sink as the invocation that started it.

An unreadable state, whether from another major version or garbled, is never an error. Its header still narrows, so an offline invocation stays offline, and OCX prints one warning.

The running OCX’s parsed flags are authoritative. They overwrite what the inherited state says, so a stale exported OCX_OFFLINE=1 cannot override an outer ocx invoked without --offline. Under --clean the child environment starts empty and the state is written afresh from the outer OCX’s parsed settings. No ambient shell export can bypass this.

Some settings have no command-line flag: OCX_DEFAULT_REGISTRY, OCX_INSECURE_REGISTRIES, OCX_ALLOW_YANKED, OCX_NO_PROJECT, OCX_NO_CONFIG_REFRESH and OCX_NO_UPDATE_CHECK. The child reads them from the environment it inherits. Two of them also have a config counterpart: OCX_DEFAULT_REGISTRY overlays [registry] default, and OCX_INSECURE_REGISTRIES unions with [registries.<name>] insecure.

Some variables are deliberately outside what travels. OCX_LAZY_MODE, OCX_LAZY_REPORT and the three toolchain settings OCX_TOOLCHAIN_ACTIVATE, OCX_TOOLCHAIN_PINNED and OCX_TOOLCHAIN_UPDATE change when or how content reaches PATH. They never change which digest resolves, so a child reads its own environment. The same holds for OCX_SELF_UPDATE, OCX_UPDATE_CHECK_INTERVAL, OCX_CEILING_PATH and OCX_SIGSTORE_TRUSTED_ROOT. OCX_PROJECT selects per invocation and is never forwarded. A tool started under ocx --project <file> exec discovers its own project, and can pass --project or --global to a nested OCX without a conflict.

Four credentials are scrubbed from every child, plugins (ocx-<name>) included: OCX_IDENTITY_TOKEN, OCX_KEY_PASSWORD, OCX_SIGNING_KEY and OCX_ANNOUNCE_GIT_TOKEN. The registry tokens OCX_AUTH_<REGISTRY>_TOKEN are not scrubbed. A child inherits them unchanged under the default and --isolate modes, and under --clean they are absent. Launcher children re-enter via ocx launcher exec using a local package root rather than a registry, so they never need credentials. The runner variables that --ci and --ci-annotations read are not forwarded either, because the CI output files are runner-managed paths.

Execution records carry the composition mode of the invocation as envMode. Execution records covers it.