Configure OCX defaults

Change OCX defaults, such as the default registry or the mirror map, with a TOML configuration file.

OCX reads settings from three layers: config files, environment variables and CLI flags. A higher layer wins, so a CLI flag overrides an environment variable, which overrides a config file.

Where the config files live

Config files are in TOML format and come from three tiers:

Tier	Path
System	/etc/ocx/config.toml
User (Linux)	$XDG_CONFIG_HOME/ocx/config.toml or ~/.config/ocx/config.toml
User (macOS)	~/Library/Application Support/ocx/config.toml (XDG_CONFIG_HOME is not consulted on macOS)
OCX home	$OCX_HOME/config.toml (default: ~/.ocx/config.toml)

OCX loads the files from lowest to highest and merges them. It skips missing files silently, and no config file is required.

Add a file or skip the discovered ones

Explicit additions. --config FILE or OCX_CONFIG=/path/to/file.toml layers an extra file on top of the discovered chain. This refines ambient config without rewriting it.

Set both and --config sits at the highest file-tier precedence. The specified file must exist. To disable an ambient OCX_CONFIG without unsetting it, set it to the empty string.

Kill switch. OCX_NO_CONFIG=1 skips the discovered chain (system, user, $OCX_HOME) but leaves explicit paths intact. Combine it with --config for a fully hermetic CI load: OCX_NO_CONFIG=1 ocx --config ci.toml ....

Change a default

Put the setting in a file of one of the tiers above, for example $OCX_HOME/config.toml (you create the file). This content makes ghcr.io the registry for bare package names, from the next command on:

[registry]
default = "ghcr.io"

Check that OCX reads a file the way you meant before you install it. ocx config test only previews: it merges the file onto this machine’s config, prints the result and applies nothing. The report has a Default registry row that reads ghcr.io, and it lists any key OCX did not recognize:

ocx config test ./config.toml

Every key, its type and its default are in the configuration reference. The registry setting is registry.default.

Next steps

• Route traffic through a corporate mirror sets the [mirrors] table.
• Authenticate with a private registry gives OCX credentials.
• Manage configuration for a fleet publishes one config to every host.

Learn more

Configuration reference: every config key, type, default and error string. Configuration In Depth: discovery tier rationale, merge semantics and worked examples (Docker base image, hermetic CI, portable install).