Skip to content

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, on Windows %ProgramFiles%\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)
User (Windows) %APPDATA%\ocx\config.toml
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/a.toml:/path/b.toml layers extra files on top of the discovered chain. OCX_CONFIG is a list separated like PATH (; on Windows), a later entry wins, and --config loads after it. This refines ambient config without rewriting it.

Set both and --config sits at the highest file-tier precedence. Every specified file must exist, and a list holds at most 32, or the command exits 78. The list still loads under OCX_NO_CONFIG. A CI image recipe shows the list in use. 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:

Terminal window
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