Environment & exit codes

Every variable this SDK reads or writes, and how an ocx exit code becomes a Python exception. The composition itself happens in one place — _env.build_spawn_env() — described conceptually in Errors & credentials; this page is the exhaustive wire-level table.

Neutralized on every spawn

Dropped from the ambient environment before anything else, regardless of configuration — an inherited value here would silently retarget or mis-scope a call. The drop is case-insensitive: ocx_no_verify goes the same way OCX_NO_VERIFY does, because a Windows child resolves an environment lookup case-insensitively and would read either spelling.

Variable	Why
OCX_PROJECT	The SDK always targets a project through an explicit --project.
OCX_GLOBAL	Same reasoning — global scope is explicit, never ambient.
OCX_QUIET	The SDK controls output verbosity through its own presentation flags.
OCX_NO_VERIFY	A silent kill switch for signature verification — a skipped verification looks identical to a passed one. Say it at the call site instead: install(..., verify=False) / pull(..., verify=False), whose argv flag outranks the variable.
OCX_NO_HOOK	Governs the per-prompt shell hook, which a spawned child never renders.
OCX_NO_COMPLETIONS	Its sibling in the same ladder, for the same reason.

OCX_SIGSTORE_TRUSTED_ROOT is cleared too, one step later — it is popped by the config pass rather than the neutralization pass, because OcxConfig.sigstore_trusted_root can put a value back. It redefines what “trusted” means and outranks [trust.sigstore], so an inherited value could repoint Fulcio, CT, and Rekor while every install still reported verified.

Written from OcxConfig

_env.build_spawn_env() maps OcxConfig fields onto these. A plain bool field is set-only — False means “not requested”, and the host’s ambient value (if any) survives. A field typed X | None can actively clear an ambient value; None means “leave the host’s value alone” — except for the three rows marked always written, OCX_NO_UPDATE_CHECK, OCX_NO_CONSENT and OCX_SIGSTORE_TRUSTED_ROOT, where saying nothing has to mean the SDK’s default rather than whatever the host exported.

Every value the SDK writes here — and every ambient value it clears — replaces the host’s answer for that name in any case spelling, for the same reason the neutralization table gives. A field the SDK does not write leaves the ambient value exactly as the host spelled it.

Variable	OcxConfig field	Notes
OCX_OFFLINE	offline: bool	Set to 1 when True; otherwise unwritten.
OCX_FROZEN	frozen: bool	Same set-only shape.
OCX_NO_CONFIG	no_config: bool	Same set-only shape.
OCX_NO_UPDATE_CHECK	no_update_check: bool	Always written ("1" or "0") — its SDK default is True, so a caller asking for the update check back has to be able to beat an ambient OCX_NO_UPDATE_CHECK=1.
OCX_NO_CONSENT	consent: bool	Always written ("1" unless consent=True). Without it every add/lock/pull/exec/update/init stamps state/projects/<key>/consent.json, which is what lets a shell prompt in that directory activate the project — a side effect a program step should not leave behind. ocx exec forwards it to nested ocx. This is the per-project stamp, not the shell-activation consent ocx shell allow records.
OCX_HOME	home: Path | None
OCX_CONFIG	config: Path | None
OCX_INDEX	index: Path | None
DOCKER_CONFIG	docker_config: Path | None	Keep the directory 0700 — it holds registry credentials.
OCX_JOBS	jobs: int | None
OCX_MIRRORS	mirrors: Mapping[str, str] | None	Serialized as JSON.
OCX_MANAGED_CONFIG	managed_config: str | None	MANAGED_CONFIG_DISABLED ("") force-disables an ambient managed-config tier; skipped entirely under no_config.
OCX_NO_CONFIG_REFRESH	no_config_refresh: bool | None	True writes 1; False explicitly clears an ambient value; None leaves it alone.
OCX_INSECURE_REGISTRIES	insecure_registries: Collection[str] | None	Fail-closed: any explicit value, including (), replaces the ambient set entirely rather than merging with it.
OCX_SIGSTORE_TRUSTED_ROOT	sigstore_trusted_root: str | Path | None	Always written: a value sets it, None pops any ambient one. None therefore means ocx’s own root of trust, not the host’s — see the neutralization table for why. Typed str | Path because CI configuration usually interpolates it as text.
OCX_RECORDS_DIR	records_dir: Path | None	Where exec writes its execution record; the directory must already exist. The per-call records_dir= on every exec/spawn verb overrides it.
OCX_RECORDS_NAME	records_name: str | None	The record’s filename template ({time}, {host}, {pid}, {rand}). Per-call records_name= overrides it.
OCX_TOOLCHAIN_DIR	toolchain_dir: Path | None	Where the project toolchain links live. OCX_TOOLCHAIN_PINNED and OCX_TOOLCHAIN_ACTIVATE are deliberately not modelled — the former is the weakest tier under pinned= on env/exec, the latter is a shell-session concern.
OCX_ANNOUNCE_TOKEN	forge_token: str | None	The forge API credential announce/claim use — the top rung of the identity ladder. repr=False; redacted.
OCX_ANNOUNCE_GIT_TOKEN	forge_git_token: str | None	The push-leg credential for transport="git". repr=False; redacted.
OCX_ANNOUNCE_GIT_USERNAME	forge_git_username: str | None	The username the git push leg authenticates as.

Continues on Environment & exit codes: Auth.