kdcokenny/ocx: Isolated OpenCode Profiles and SHA-256 Verified Components

The problem OCX solves: your OpenCode config does not travel

OpenCode reads configuration from the project it is running in. That is fine when you own the repository. It is awkward when you clone a client codebase, or a repository where you are a contractor for two weeks, and your agents, skills, plugins and commands are simply absent. Copying your global config into the working tree pollutes a repo you do not own; leaving it out means you work with a bare agent.

OCX addresses that by separating the configuration you carry from the project you are standing in. The README frames it as "Your OpenCode config, anywhere", and the mechanism is a profile: a named bundle of OpenCode settings plus its own registries. The intended audience is engineers who move between repositories often and want the same agent setup in each one without editing any of them. A secondary audience is anyone assembling a shareable OpenCode setup for a team, since profiles can be published to a registry and installed by name.

How profiles, registries and exclusion patterns fit together

A profile is the unit of isolation. The README states that each profile has isolated registries, and that profiles control what OpenCode sees through exclude and include patterns. That second part is the load-bearing design decision: a profile is not just a settings file, it is a filter over the project's own instruction files. You decide which of the host repository's files the agent is allowed to read.

The README is explicit that the default is not safe by accident. An empty exclude list includes all project instruction files, and the default profile template ships a secure exclude list so that a fresh profile does not immediately ingest everything in the tree. For trusted repositories the documentation suggests editing the profile to loosen that template, and links a Lock Down Recipe for the opposite direction.

Components are the second layer. They are installed with ocx add and copied into .opencode/ rather than resolved from node_modules. The README calls this the ShadCN model and states the intent plainly: you own the code, and you can customize it. Integrity is handled separately, with every component SHA-256 verified, which the README compares to Cargo's dependency resolution and verification. The claim that follows from that pairing is narrow but real: the agent does not run code you have not reviewed, because the code is sitting in your project where you can read it.

Configuration merging is the third piece. The README says OpenCode config merges safely between profile and local settings, so a profile does not simply overwrite whatever the repository already declares.

Installing OCX and launching your first profile

The install script is the recommended path on macOS and Linux. It fetches a shell script from the project's documentation domain and runs it, and the README says it handles PATH configuration automatically or prints instructions when manual setup is needed.

curl -fsSL https://ocx.kdco.dev/install.sh | sh

There is also an npm route that works on any platform, but with a caveat the README states directly: the npm package runs with Bun at runtime, so bun must be on your PATH before you use it. Node.js alone is not sufficient. If you do not have Bun, the README points to the standalone binaries from the install script or GitHub Releases.

npm install -g ocx

Once installed, the one-time setup writes your global configuration. The --global flag is what puts the profile outside any single repository.

ocx init --global

The README's quick start then installs a profile from a registry by source identifier and registry URL, and launches OpenCode against it. After the launch command you should see OpenCode start with the profile's configuration rather than the repository's.

ocx profile add ws --source tweak/p-1vp4xoqv --from https://tweakoc.com/r --global
ocx oc -p ws

For project-scoped work rather than global profiles, the flow is a local init, a named registry, and a component install. The README notes components land in .opencode/, not node_modules.

ocx init
ocx registry add https://registry.kdco.dev --name kdco
ocx add kdco/workspace

If you want to publish your own registry rather than consume one, the README gives a scaffold command through npx.

npx ocx init --registry my-registry

Where OCX gets thin: rollback, scope and the Bun dependency

The README documents installation, profile creation, component addition and registry scaffolding. It does not document rollback. There is no described command for reverting a profile to a previous state, no version pinning syntax for profiles shown in the README, and no uninstall or removal command in the command table. If you install a profile from a registry and it turns out to configure your agent badly, the README does not say how to step back. That is a real gap for a tool whose selling point is that you control what the agent sees.

The Bun requirement is a second constraint. The npm installation path is advertised as working on any platform, but the README immediately qualifies it: the package runs with Bun at runtime and Node.js alone is not sufficient. On a machine where you cannot install Bun, the npm route is not a fallback at all, and you are dependent on standalone binaries being available for your platform. The README's phrasing on that point is hedged ("when available"), which suggests the binary matrix is not guaranteed to cover every target.

Isolation is also narrower than the word suggests. Profiles isolate registries and filter which project files OpenCode sees, but the README describes OpenCode config as merging between profile and local settings. Merging is not the same as overriding. If a repository declares settings that conflict with your profile, the documentation does not spell out which side wins in each case.

Finally, the security posture depends on you reading the template. The README's own security note says an empty exclude list includes all project instruction files, and that loosening the default is something you do deliberately for trusted repos. A user who installs a profile and never inspects it is trusting whoever authored that profile's exclude list.

OCX versus the plain OpenCode config directory

The obvious alternative is not another package manager. It is OpenCode's own configuration, kept in a dotfile repository and symlinked or copied into place, which is what many people do today. The difference in approach is where the configuration lives and who resolves it.

With a dotfile repo, you own the files and you own the merge problem. There is no registry, no source identifier, no integrity check, and no per-project filter over which instruction files the agent reads. Copying your config into a client repository is a manual, error-prone act, and the exclude patterns, if you have any, are whatever you wrote by hand.

OCX moves resolution into a CLI. Profiles are installed by name from a registry, components are SHA-256 verified, and exclusion is a first-class part of the profile rather than an afterthought. The cost is a dependency on the OCX toolchain and on registries being reachable, plus the Bun runtime requirement for the npm path. If your setup is a handful of files and you only work in repositories you own, the dotfile approach has fewer moving parts and no runtime constraint. OCX earns its place when the number of repositories, or the number of people who need the same setup, grows past what manual copying can handle.

Maintenance, licence and what upgrading costs you

The repository is not archived, and the last push was on 2026-08-18. The most recent release listed is v2.0.15 on 2026-08-17, with v2.0.14 and v2.0.13 both on 2026-07-28. That is a release cadence measured in weeks, and the version series is well past 2.0, so the project has been through at least one major revision.

The licence is MIT, declared both in the README and in the repository package.json. For adopters that means the usual MIT permissions and the usual absence of warranty; it does not impose copyleft obligations on your own code. Note that the root package.json is marked private and carries version 0.0.0, so it is the workspace root rather than the published CLI. The published artifact is the ocx package on npm, and its version is what the npm badge tracks. If you are auditing what you install, check the version of the package you actually fetch rather than the version in the repository root.

Upgrade cost is mostly the profile format. Because profiles are installed from registries and components are verified by hash, an upgrade that changes how a registry is addressed or how a profile is laid out will show up as a failed install rather than silent drift. The README does not describe a migration command for profiles across major versions, so treat a major bump as something to test against a scratch profile before you point it at a working repository.

The project also states it is not built by the OpenCode team and is not affiliated with OpenCode. That matters for support expectations: issues go to this repository, not to OpenCode's.

Editorial conclusion

Adopt OCX if you work across many repositories and want one reviewed OpenCode configuration to follow you into each of them, and if you are comfortable with Bun on the PATH. Skip it if you only ever work in one repo, or if you need a rollback story the documentation does not provide. Verify the exclude list in your default profile before you open a client codebase, and check that ocx profile list --global shows the profile you expect before launching with ocx oc -p.

Frequently asked questions

Official sources

1. kdcokenny/ocx on GitHub
2. License: MIT
3. Project website
4. README
5. Releases