Skip to content

Configuration

Keys of config.toml, from the published config schema. Tiers, precedence and the kill switch are in Configuration.

Config file locations

OCX reads each file that exists, lowest precedence first. A file over 64 KiB is refused with exit 78.

Tier Path
System /etc/ocx/config.toml, on Windows %ProgramFiles%\ocx\config.toml
User on Linux $XDG_CONFIG_HOME/ocx/config.toml, else ~/.config/ocx/config.toml
User on macOS ~/Library/Application Support/ocx/config.toml
User on Windows %APPDATA%\ocx\config.toml
OCX home $OCX_HOME/config.toml, default ~/.ocx/config.toml
Explicit OCX_CONFIG and --config

extra_ca_certs

Path to a PEM file of extra CA certificate(s), trusted for OCI registry, index and forge traffic in addition to the platform trust store.

A relative path resolves against the directory of the config.toml that declared it.

Overridden by the OCX_EXTRA_CA_CERTS environment variable, which outranks every config.toml tier unless the pair is declared in the system tier.

extra_ca_certs_pem

The extra CA certificate bundle inlined verbatim (PEM text).

This is the form a fleet receives; ocx config push inlines a path-form extra_ca_certs here.

managed

Corporate managed-configuration tier ([managed]).

Points at an operator-controlled OCI artifact that supplies a plain config.toml payload, such as mirrors, a patches pointer and a default registry. The payload is synced into local state and merged above the user config every invocation.

Absent → no managed tier configured (opt-in, seeded by ocx self setup --managed-config).

managed.interval

Background refresh throttle interval, \d+[smhd]? (bare = seconds). Defaults to "1d".

managed.refresh

Background refresh posture. Defaults to notify.

apply swaps in a drifted snapshot, notify advises ocx config update, manual refreshes only on ocx config update. CI never runs the background check.

An unknown value is ignored with a warning, so the default applies.

  • Type: string
  • Values:
    • apply: A change is applied without asking, by the background check only, which runs only on an interactive terminal, outside CI, and online.
    • notify: A change prints a stderr notice naming the command that applies it; the check probes the registry but applies nothing.
    • manual: The background check is skipped entirely; only an explicit command refreshes.
  • Default: "notify"
  • See: Manage configuration for a fleet

managed.required

Fail posture when the snapshot is required but absent.

  • true (default) — fail closed: a config error (exit 78) until ocx config update (or self setup --managed-config) syncs one.

  • false — the tier contributes nothing until synced; a throttle-gated stderr hint only.

  • Type: boolean

  • Default: true

  • See: Manage configuration for a fleet

managed.source

OCI reference for the managed-config artifact, e.g. "internal.company.com/ocx-config:user".

Absent → no managed tier configured. The OCX_MANAGED_CONFIG environment variable overrides it for one invocation.

mirrors.<name>

Per-traffic-host mirrors ([mirrors."<host>"]).

Maps a canonical upstream traffic host (e.g. "ghcr.io", "index.ocx.sh") to replacement endpoint(s), so read traffic goes to a corporate mirror instead of a blocked origin. A bare string rewrites both traffic roles for that host; a {registry?, index?} table splits per role — registry rewrites OCI distribution traffic only, index index-tree traffic only.

Replace semantics: no origin fallback. The canonical identifier and content-addressed digest stay unchanged, so an ocx.lock produced behind the mirror remains valid with direct egress and vice versa.

mirrors.<name>.index

Endpoint for index-tree traffic (/config.json, /c, /p) to this host, if an index role was declared for it.

mirrors.<name>.registry

Endpoint for OCI distribution traffic (/v2) to this host, if a registry role was declared for it (a bare string, {registry: ...}, or {registry: ..., index: ...}).

patches

Site-tier patch configuration ([patches]).

Points at an operator-controlled patch registry that provides companion packages, such as CA bundles, proxy env vars and license-server endpoints. They are layered onto unmodified upstream packages at compose time.

Absent → no patch tier configured (opt-in, not required).

patches.path

Path-template for per-package patch repositories. Default: "{registry}/{repository}".

Placeholders: {registry} — the base identifier’s registry host, slugified (characters outside [a-zA-Z0-9._-] become _); {repository} — the base identifier’s repository path.

patches.registry

OCI registry hosting patch descriptors, e.g. "internal.company.com/ocx-patches".

Absent → no patch tier configured.

patches.required

Fail posture when a matched companion is unavailable.

  • true (default) — fail closed: abort launch if a required companion cannot be resolved.

  • false — fail open: skip with a warning (suitable for non-security companions like a license-server URL or metrics endpoint).

  • Type: boolean

  • Default: true

  • See: Patch packages for your infrastructure

records

Execution-record sink ([records]).

Designates where OCX writes one JSON resolution record per tool launch — the resolved package closure with digests, plus the resolved executable. Declared in the system tier it clamps: no lower tier can redirect or disable it.

Absent → no records written (opt-in).

records.dir

Directory records are written to. Absent → recording is off.

Overridden by the --records-dir flag and the OCX_RECORDS_DIR environment variable.

records.name

Name template for each record file, e.g. {time}-{host}-{pid}-{rand}.json.

Must contain a component that varies per record, or two frames sharing a sink resolve to one path. Defaults to {time}-{pid}-{rand}.json.

Overridden by the --records-name flag and the OCX_RECORDS_NAME environment variable.

records.required

Fail posture when a record cannot be written.

true aborts the launch; false warns and proceeds. Config-file only at every tier — never settable from the environment or a flag.

Defaults false unlocked, true when SYSTEM-locked.

registries.<name>

Named per-registry configuration tables ([registries.<name>]).

Every key is an identifier prefix, always — [registry] default never dereferences through this table. The key is the package name’s domain, not the host serving the bytes: an entry keyed on the host matches no package, so its trusted_hosts never applies.

  • Type: table

registries.<name>.index

Base URL of the index.ocx.sh-protocol index this namespace resolves through, e.g. "https://index.ocx.sh", or file:///absolute/path for a local index read with no server.

Field presence is the kind marker. An entry that carries index resolves via the ocx-index protocol; one without it, or no entry at all, resolves as plain OCI, with no fallback. A file:// base is checked at startup: a relative path or a remote authority is refused.

index = "" resolves the namespace as plain OCI. A [mirrors] registry entry for the namespace in a config file you control suppresses the compiled-in index; the managed tier and OCX_MIRRORS cannot.

registries.<name>.insecure

Contact this registry over plain HTTP instead of HTTPS.

Unioned with OCX_INSECURE_REGISTRIES, except that a system-tier entry stating insecure = false locks that host shut against the env list too.

registries.<name>.signatures

Whether packages of this registry must carry publisher identities declared in the index.

One of if_declared (verify when the package declares publishers), required (refuse a package without them) or off (skip the check). Defaults to if_declared.

An unknown value is treated as required, with one warning per run.

A lock-first install in a fresh home makes no index request, so it installs without the publisher check. Set required to check those installs too: a package whose committed root declares no publishers is then refused (exit 81, publishers_required), and the error names ocx index update.

  • Type: string
  • Values:
    • if_declared: Verify against the index-declared publishers when the package declares any (the default).
    • required: Refuse a package whose index declares no publishers.
    • off: Skip the publisher check.

registries.<name>.trusted_hosts

SSRF escape hatch for this namespace’s physical registry hosts. Each entry is an exact hostname or a CIDR block whose resolved addresses skip the default-on private/loopback/link-local/metadata refusal.

A hostname entry also lets ocx package prune --forge github delete through the GitHub Enterprise packages API of a containers.<host> registry that this namespace’s index names. Only an exact hostname vouches for that; a CIDR block does not.

registry

Global registry-subsystem settings ([registry] section).

registry.default

Default registry for bare identifiers (e.g. nodejs/node:24 expands to <default>/nodejs/node:24).

Overridden by the OCX_DEFAULT_REGISTRY environment variable. Always a literal prefix (e.g. "ghcr.io", "ocx.sh") — never resolved through the [registries.<name>] table.

shell

Shell-integration settings ([shell]) — the per-prompt hook and completions toggles, plus the activation consent whitelist.

Never read from a project’s ocx.toml, only from config.toml tiers: consent read from a repository’s own file would let a clone consent to itself. Consumed by ocx self activate, ocx self setup and ocx shell state.

shell.completions

Whether shell completions load, with the same precedence as hook: --completion / --no-completion and a truthy OCX_NO_COMPLETION win.

  • Type: boolean
  • Default: unset (follows session interactivity)
  • See: Shell integration

The activation consent whitelist ([shell.consent]).

Source namespaces that activate a project whose whole lock is inside them.

One pattern, or one {include, exclude} table where exclude beats include, so “everything under ocx.sh/acme/* except the one compromised namespace” is spellable.

Patterns carved back out. Beats include wherever both match.

Patterns the policy covers. Required in the table form; an empty list drops the [shell.consent] table with a warning.

Directories that activate unconditionally, modelled on git’s safe.directory.

An entry is one exact directory, or with a trailing /* that directory and everything beneath it, matched component-wise. A bare * grants nothing.

Entries are compared literally, after separator and trailing-slash normalization, against the canonical project directory; an entry naming a symlinked checkout never matches. A leading ~ expands textually against the home directory.

A paths grant is drift-blind and writes no stamp, so revoking it is immediate.

shell.hook

Whether the per-prompt shell hook runs.

--hook / --no-hook and a truthy OCX_NO_HOOK take precedence; absent means it follows session interactivity. A higher tier’s value wins in either direction, the managed tier over a user’s own file included.

  • Type: boolean
  • Default: unset (follows session interactivity)
  • See: Shell integration

shell.modify_path

Whether ocx self setup may write PATH surfaces — shell profiles and the session-PATH stores alike. Absent means true.

shell.profiles

Which shell profile files receive the managed OCX block.

Absent means auto-detect fresh on every run; an empty list means write no profile blocks at all.

toolchain_dir

Root directory holding every project’s toolchain tree, each at <root>/<project-key>/toolchain/.

The global toolchain tree ignores this key, and the directory need not exist yet.

trust

Identity-pinned verification policies ([[trust.policy]]).

Unlike every other section, trust policies array-append across the config.toml tiers rather than replace — the operator trust set is the union of system, user and $OCX_HOME. At verify time this operator set takes precedence over the project ocx.toml.

Consumed by ocx package verify.

trust.policy

The declared policies. Empty when [trust] is present but lists none.

trust.policy.builder

Expected SLSA provenance builder identity, matched against the provenance predicate during attestation verify.

Ignored in signature mode, without an error.

trust.policy.scope

Which packages this policy applies to: one prefix pattern, or an include/exclude set of them.

A pattern matches on /-separated path-segment boundaries, and an absent scope is a catch-all.

scope = "ghcr.io/acme/*"
scope = { include = ["ghcr.io/acme/*"], exclude = ["ghcr.io/acme/experimental/*"] }

trust.policy.scope.exclude

Patterns carved back out. Beats include wherever both match.

trust.policy.scope.include

Patterns the policy covers. Empty is a catch-all.

trust.policy.signers

The signers this policy accepts: an ANY-of set, each entry tagged kind = "keyless" or kind = "key".

signers = [
{ kind = "keyless", identity = "release@acme.example", oidc_issuer = "https://accounts.google.com" },
{ kind = "key", key = "etc/acme-release.pub" },
]

Every added entry widens what verifies, and an empty set is a configuration error, not a catch-all.

trust.policy.signers.claims.<name>

Fulcio certificate claims that must all match, keyed by claim name or raw OID.

Every listed claim must match, and values compare as exact strings. A key is a known claim name (build_signer_uri, source_repository_identifier, source_repository_owner_identifier, build_trigger, build_signer_digest) or a raw OID under 1.3.6.1.4.1.57264.1.; an unknown name matches nobody.

Alone or beside identity / identity_regexp.

trust.policy.signers.identity

Exact expected certificate SAN (byte-equal).

Mutually exclusive with identity_regexp.

trust.policy.signers.identity_regexp

Regex the certificate SAN must match in full (anchored \A…\z).

Mutually exclusive with identity.

trust.policy.signers.key

A key reference ([scheme://]<rest>), the same spelling --key takes on the command line.

Mutually exclusive with key_pem, and refused in a managed-config payload.

trust.policy.signers.key_pem

Verbatim SPKI PEM.

Mutually exclusive with key.

trust.policy.signers.kind

Selects the variant of this entry; the other fields depend on the value.

  • Type: string
  • Values:
    • keyless: { kind = "keyless", identity | identity_regexp, oidc_issuer }.
    • key: { kind = "key", key | key_pem }.
    • unknown: A kind this build does not know — an entry written by a newer OCX.
  • See: Trust signers with a policy

trust.policy.signers.oidc_issuer

Exact expected OIDC issuer URL (byte-equal).

trust.sigstore

Sigstore trust material for a self-hosted stack ([trust.sigstore]).

Read from the operator config.toml tiers only. The project ocx.toml also accepts a [trust] table, but its sigstore sub-table is never consulted.

trust.sigstore.fulcio_url

Default Fulcio base URL for ocx package sign when --fulcio-url is omitted.

trust.sigstore.rekor_upload

Fleet-wide default for uploading a key-mode signature to the transparency log, when neither --rekor-upload nor --no-rekor-upload is given.

Absent means off; keyless signing always uploads and ignores this field.

trust.sigstore.rekor_url

Default Rekor base URL for ocx package sign / verify when --rekor-url is omitted.

trust.sigstore.trusted_root

Path to a Sigstore trusted-root JSON, or a directory holding trusted_root.json.

A relative path resolves against the directory of the config.toml that declared it. It is rewritten to absolute at load time, so the same value names the same file whatever the working directory.

Mutually exclusive with trusted_root_json.

trust.sigstore.trusted_root_json

The trusted-root document inlined verbatim.

This is the form a fleet receives: ocx config push reads a path-form trusted_root at publish time and inlines it here. Mutually exclusive with trusted_root.

update

Background update checks ([update]): the posture for OCX itself and for the toolchain, plus the interval between checks.

A personal setting, read from config.toml only: a managed payload’s [update] is ignored and an ocx.toml refuses it. An unknown value never fails a command.

update.interval

Minimum time between two checks, \d+[smhd]? (bare digits = seconds); "0" checks on every command. Defaults to "1d".

Overridden by the OCX_UPDATE_CHECK_INTERVAL environment variable.

update.self

What OCX does when a newer OCX is published: apply installs it after the command finishes, notify (default) prints a notice, manual never checks. Overridden by the OCX_SELF_UPDATE environment variable.

  • Type: string
  • Values:
    • apply: A change is applied without asking, by the background check only, which runs only on an interactive terminal, outside CI, and online.
    • notify: A change prints a stderr notice naming the command that applies it; the check probes the registry but applies nothing.
    • manual: The background check is skipped entirely; only an explicit command refreshes.
  • Default: "notify"
  • See: Update or uninstall OCX

update.toolchain

What OCX does when a locked tool’s tag has moved: notify (default) prints a notice, manual never checks. apply is treated as notify: only ocx update moves a pin.

Overridden by the OCX_TOOLCHAIN_UPDATE environment variable.

  • Type: string
  • Values:
    • apply: Read as notify: only ocx update moves a pin.
    • notify: A change prints a stderr notice naming the command that applies it; the check probes the registry but applies nothing.
    • manual: The background check is skipped entirely; only an explicit command refreshes.
  • Default: "notify"
  • See: Update or uninstall OCX