Skip to main content
OCX stores its own metadata in ocx.jsonc. OpenCode settings belong in native files such as opencode.jsonc and cli.json. OCX does not merge or translate those native settings at launch.

​
Locations

For an absolute XDG_CONFIG_HOME, replace ~/.config below with its value. A relative value falls back to the home configuration directory. A project destination is the directory you run the command in, or --cwd <directory>, with .opencode/ appended. OCX does not search upward for a different project’s metadata.

​
Global metadata

Initialize with ocx init --global, or set a default with ocx profile use:
lockRegistries is a management policy, not a security boundary against someone who can edit the file. Profile metadata has its own smaller schema and does not accept this field.

​
Profile metadata

A profile’s sources are independent of global sources and other profiles. Native config supports its own schema and fields; do not put models, providers, or plugins in ocx.jsonc.

​
Project metadata

Initialize from a repository with ocx init --project:
Project metadata uses the global metadata schema, but defaultProfile has no selection effect there. Only the global file can set the launch default. Project registry sources do not become profile sources, even when the profile inherits native project configuration.

​
Registry authentication

Add request headers by editing the relevant scope’s metadata:
OCX expands ${ENV_VAR} for registry requests. An unset variable fails the request instead of sending an unresolved value. Resolved secrets are not written into receipts. Avoid putting literal credentials in shared metadata or registry URLs. OpenCode’s {env:...} and {file:...} references are a separate native feature; OCX does not expand them.

​
Inspect and edit

Choose exactly one scope. config show reports OCX metadata, not a merged native configuration. config edit opens ocx.jsonc using VISUAL, then EDITOR, then vi; arguments such as code --wait are supported. Edit native files directly with your editor. OCX metadata accepts JSONC comments and trailing commas. Unknown OCX fields are rejected; keeping OpenCode and OCX settings in separate files prevents confusing one contract with the other.

​
Selection and environment

At launch OCX sets OPENCODE_CONFIG_DIR to the profile and the native project-discovery switch from projectConfig. It clears inherited inline/alternate config overrides and old OCX bridge variables so they do not silently select a different setup. Other native environment settings retain their native behavior. See profile discovery for nested AGENTS.md behavior and launch options for private-server routing.