OcxConfig (1 of 3)
OcxConfigclassdataclass#
Re-exported from
ocx_sdk._configView sourceclass OcxConfig(home: Path | None = None, offline: bool = False, frozen: bool = False, config: Path | None = None, no_config: bool = False, managed_config: str | None = None, auth: Mapping[str, Auth] = dict[str, Auth](), insecure_registries: Collection[str] | None = None, sigstore_trusted_root: str | Path | None = None, docker_config: Path | None = None, index: Path | None = None, jobs: int | None = None, log_level: LogLevel | None = None, mirrors: Mapping[str, str] | None = None, no_update_check: bool = True, no_config_refresh: bool | None = None, consent: bool = False, records_dir: Path | None = None, records_name: str | None = None, toolchain_dir: Path | None = None, forge_token: str | None = None, forge_git_token: str | None = None, forge_git_username: str | None = None, retry: RetryPolicy | None = None, timeout: float | None = None)Policy for every ocx process a handle spawns.
Containers are snapshotted at construction — the mappings as read-only
proxies, insecure_registries as a tuple — so neither mutating the argument
afterwards nor reaching into the field can rewrite a config a handle already
holds. Derive a variant with Ocx.with_config(...)
rather than reaching for a mutation that the frozen dataclass refuses.
Attributes
| Name | Type | Description |
|---|---|---|
home | Path | None | $OCX_HOME for the spawned process; None keeps ocx’s default. |
offline | bool | Refuse every network access. |
frozen | bool | Refuse any lockfile change. |
config | Path | None | Explicit config.toml; None keeps ocx’s discovery chain. |
no_config | bool | Hermetic mode — drops the discovered chain and the managed
tier. Wins over managed_config when both are set, which is ocx’s
own precedence, not an SDK invention. |
managed_config | str | None | OCI reference of the managed config tier.
MANAGED_CONFIG_DISABLED force-disables an ambient one; None
leaves the ambient setting alone. |
auth | Mapping[str, Auth] | Credentials per registry, keyed lowercase. An entry wins over an
ambient OCX_AUTH_<SLUG>_* for the same registry, whatever case
that variable spells the slug in. |
insecure_registries | Collection[str] | None | Registries reachable over plaintext HTTP. None
inherits the ambient set; any explicit value replaces it entirely,
so () blocks an ambient re-enable (fail-closed). |
sigstore_trusted_root | str | Path | None | The Sigstore trusted root to verify signatures
against, for air-gapped verification against a private root of
trust. None is not “leave the ambient value” here, unlike
the other path-shaped fields: it means ocx’s own default root, and
_env pops an ambient OCX_SIGSTORE_TRUSTED_ROOT to enforce that.
The variable redefines what “trusted” means and outranks the
config file, so an ambient one could otherwise repoint Fulcio, CT,
and Rekor at an attacker’s material while every install still
reported verified.
The path travels verbatim, as home, config, index and
docker_config do: ~ is not expanded, and a relative path
resolves against the child’s working directory, not the
caller’s. That is acceptable rather than sloppy, because a path
ocx cannot read is not a path it falls back from — an explicit
override is read with ?, so an unreadable one aborts the command
at exit 74 (IoError) instead of quietly verifying against the
default root. A wrong value fails loudly; it never becomes a
silent trust substitution, which is the hazard this field exists
to close. Pass an absolute path when the call must not depend on
where the child starts. |
docker_config | Path | None | Directory for DOCKER_CONFIG. Keep it 0700 — it holds
registry credentials. |
index | Path | None | Explicit index path; None keeps ocx’s default. |
jobs | int | None | Parallel job cap; None keeps ocx’s default. |
log_level | LogLevel | None | ocx trace verbosity. At 'trace' ocx may print secrets of
its own; the SDK can only redact the values it was given. |
mirrors | Mapping[str, str] | None | Registry host to mirror host, serialized into OCX_MIRRORS. |
no_update_check | bool | Suppress ocx’s update check. True by default — an
SDK call is a program step, not an interactive session. |
no_config_refresh | bool | None | Suppress the managed-config refresh; None leaves
the decision to whoever owns that tier. |
consent | bool | Let the project-tier mutators (add, lock, pull, exec,
update, init) record the per-project consent stamp that lets
a shell prompt in that directory activate the project. False by
default — an SDK call is a program step, and a stamp it left
behind would make the project live at the developer’s next prompt
without anyone having run ocx shell allow. Travels as
OCX_NO_CONSENT, written either way so an ambient value cannot
decide it. This is the per-project stamp, not the shell-activation
consent ocx shell allow records — that command is not wrapped. |
records_dir | Path | None | Where exec and package exec write execution
records — OCX_RECORDS_DIR. None leaves it to [records] dir
in the project (or an ambient value); without any, no record is
written. The per-call records_dir= on the exec verbs outranks
this. |
records_name | str | None | The record filename template — OCX_RECORDS_NAME.
None leaves it to [records] name or ocx’s default. |
toolchain_dir | Path | None | The root ocx renders project toolchains under —
OCX_TOOLCHAIN_DIR — instead of <project>/.ocx/toolchain/.
None keeps ocx’s default. OCX_TOOLCHAIN_PINNED and
OCX_TOOLCHAIN_ACTIVATE are deliberately not modelled: the
first is the weakest tier of a choice pinned= makes at the
call site, the second governs shell activation the SDK never
performs. |
forge_token | str | None | The forge API credential package.announce and
package.claim open their request with — OCX_ANNOUNCE_TOKEN.
None leaves an ambient one alone; explicit wins over ambient,
as auth does. Redacted from every log and error surface. |
forge_git_token | str | None | The push secret for transport="git" —
OCX_ANNOUNCE_GIT_TOKEN. Falls back to forge_token upstream
when unset. Redacted likewise. |
forge_git_username | str | None | The username the git transport pushes as —
OCX_ANNOUNCE_GIT_USERNAME. Not a secret. |
retry | RetryPolicy | None | Retry policy for failures ocx marked transient; None disables
retrying. |
timeout | float | None | Per-attempt budget in seconds; None waits indefinitely. |