ocx: Portable OpenCode Profiles Without Touching the Repo
OpenCode extension manager with portable, isolated profiles. Your setup, anywhere.
At a glance
- What is it?
- ocx is a TypeScript CLI that installs OpenCode profiles from registries and launches OpenCode against them, so your agent config travels with you instead of living in each project. The design is closer to Cargo plus ShadCN than to a plugin manager, and the security model depends entirely on which exclude patterns your profile ships with.
- Who is it for?
- Adopt ocx if you work across many repositories and want one reviewed OpenCode configuration to follow you into all of them, or if you already distribute OpenCode components and want a registry format with SHA-256 verification. Do not adopt it if you expect a single global config to be enough, or if you cannot guarantee Bun on the machines that run the npm install path.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem ocx Solves: Config That Follows You Into Someone Else's Repo
OpenCode reads configuration from the project it runs in. That is fine when the project is yours. It stops being fine when you clone a repository you did not write, open your agent inside it, and the agent picks up instruction files and settings that came with the checkout. The README frames the goal as working in any repo without modifying it: your config, their code. The mechanism for that is a profile, which the documentation describes as controlling what OpenCode sees through exclude and include patterns. Each profile also carries its own isolated registries, which the README lists under a security heading rather than a convenience one. The intended user is someone who moves between repositories all day and wants one reviewed setup rather than a per-project rewrite. It is not aimed at a single-repo team that has already committed a working .opencode directory, because that team has the problem ocx solves already solved.
Profiles, Registries and the Merge Rule
A profile is the unit of isolation. It holds exclude and include patterns that decide which files OpenCode can see, plus its own registry set. The README states that OpenCode config merges safely between profile and local settings, so a profile does not replace project configuration wholesale; it layers over it. That merge is the part worth understanding before you commit to the tool, because it determines whether a project can override your profile and in which direction. The README does not spell out the precedence order, and that omission matters: if you are relying on a profile to keep a hostile instruction file out of context, you want to know whether a local setting can reintroduce it. Registries are the distribution half. A registry publishes profiles and components, and the CLI installs from one with a source path and a from URL, as in the quick start command that pulls a profile from tweakoc.com. Components are the smaller unit: individual pieces added to a project rather than a whole profile.
Components Are Copied, Not Installed Into node_modules
The README is explicit that ocx follows the ShadCN model. Components are copied into .opencode/ in your project, not resolved from node_modules at runtime. The stated reason is ownership: you can read and edit what lands there. The README also compares the resolution behaviour to Cargo and states that every component is SHA-256 verified, with the line your AI agent never runs code you haven't reviewed. Those two properties pull in different directions and the documentation does not reconcile them. A copied component is editable, which means the hash that verified it at install time no longer describes what is on disk. Verification protects the install step, not the file after you have touched it. That is a reasonable design, but it means the SHA-256 check is a supply-chain control at fetch time rather than an ongoing integrity guarantee. If you were expecting the second thing, adjust the expectation.
Getting It Running: Bun, init, and the Profile Commands
Installation offers two paths. On macOS and Linux the README recommends curl -fsSL https://ocx.kdco.dev/install.sh | sh, which it says handles PATH configuration or prints manual instructions. The npm path is npm install -g ocx, and the README adds a constraint that is easy to miss: the npm package runs with Bun at runtime, so bun must be on PATH before you use it. Node.js alone is not sufficient. If Bun is not an option, the README points at standalone binaries from the install script or GitHub Releases when available. Setup is a one-time ocx init --global. Installing a profile takes ocx profile add <name> --source <registry/profile> --from <url> --global, and cloning an existing one is ocx profile add <name> --clone <existing> --global. You launch OpenCode against a profile with ocx oc -p <name>, list profiles with ocx profile list --global, and edit global config with ocx config edit --global. The component path is separate: ocx init for local setup, ocx registry add https://registry.kdco.dev --name kdco to register a source, then ocx add kdco/workspace. Registry scaffolding uses npx ocx init --registry my-registry.
The Exclude List Is the Security Boundary, and It Ships Open by Default
The README carries a security note that deserves more prominence than it gets. An empty exclude list includes all project instruction files. The default profile template ships what the README calls a secure exclude list, and the guidance for trusted repos is to edit the profile and loosen that list. Read that carefully: the safe state depends on a template you did not write, and the failure mode of getting it wrong is silent. Nothing in the described workflow blocks a launch because the exclude list is permissive. A user who clones a profile, edits the patterns, and removes one entry gets no warning that project instruction files are now in context. The lock-down recipe lives in the docs rather than in the CLI output. For anyone running an agent inside repositories they do not control, that is the single setting to audit first, and the README treats it as a note rather than a gate.
Where ocx Is the Wrong Tool
If your work happens inside one repository that you own, ocx adds a layer you do not need. A committed .opencode directory in that repo is simpler, has no runtime dependency on Bun, and needs no registry. The tool's value comes from repetition across repos and machines, and a single-repo workflow has none of that repetition. The second case is subtler. ocx isolates what OpenCode sees, but the README does not claim it sandboxes execution. Profiles and exclude patterns govern context and configuration. If you are looking for a boundary that stops an agent from running a command in a checked-out repository, this is not that boundary, and the documentation does not present it as one. The third case is distribution: if you only want to share a configuration with two colleagues, a git repository holding the .opencode directory does the job without a registry, a source path, and a from URL to maintain.
How This Differs From Committing a .opencode Directory
The obvious alternative is the one most OpenCode users already have: put your configuration in .opencode/ at the root of each project and commit it. That approach is transparent and needs no tooling. Its limitation is that it is per-project by construction, so the same configuration has to be copied or vendored into every repository, and updating it means a commit in each one. ocx inverts the direction. Configuration lives in a profile outside the repository, is installed from a registry with a source identifier and a URL, and is applied at launch with ocx oc -p <name>. The trade-off is that the configuration is now a dependency with a version, a source, and an update path, which is more moving parts than a committed directory. The README's own comparison points elsewhere, to ShadCN for the copy-in model and to Cargo for dependency resolution and integrity checks, and both of those analogies describe a package manager rather than a dotfile sync tool. That is the honest framing: ocx is a package manager for agent configuration, with the operational weight a package manager implies.
Maintenance, Licensing and What the Repository Does Not Say
The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are preserved. That is the whole of the licence implication visible here; anything beyond it depends on the licences of the registries and components you install, which ocx does not appear to surface. Release cadence is visible in the repository metadata: v2.0.15 landed on 2026-08-17, with v2.0.14 and v2.0.13 both on 2026-07-28, and the last push to main is dated 2026-08-18. That is a steady patch rhythm, and the version numbering suggests the project is past its first major rewrite. The README does not describe an upgrade command, a migration path between major versions, or what happens to installed profiles when the CLI changes shape. The npm path also inherits Bun as an ongoing runtime requirement, so every machine that installs via npm carries that dependency forward. On registries, the README does not state how a registry is trusted, who can publish to one, or what happens when a registry disappears. The SHA-256 verification covers what you fetched, not whether the source was worth fetching.
Editorial conclusion
Adopt ocx if you work across many repositories and want one reviewed OpenCode configuration to follow you into all of them, or if you already distribute OpenCode components and want a registry format with SHA-256 verification. Do not adopt it if you expect a single global config to be enough, or if you cannot guarantee Bun on the machines that run the npm install path. Verify two things before trusting it with untrusted code: the contents of your profile's exclude list, since an empty one includes every project instruction file, and whether the registries you add are ones you actually control or have reviewed.
Community notes