Registry System Overview

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/schemas/registry.ts
• packages/cli/src/lib/build-registry.ts
• packages/cli/src/commands/add.ts
• packages/cli/src/commands/init.ts
• packages/cli/src/commands/update.ts
• README.md
• AGENTS.md

The OCX Registry System is a decentralized distribution mechanism for OpenCode components, including agents, skills, plugins, and bundles. Following a "Copy. Paste. Own." philosophy, the system allows developers to build, host, and consume versioned collections of AI extensions that are merged directly into local project environments.

The system facilitates the entire lifecycle of a component: from scaffolding a new registry using the CLI, defining components via a JSONC manifest, building them into a static distribution format, to installing them into projects with automatic dependency resolution and integrity verification.

Sources: README.md:14-25, AGENTS.md:7-12

Registry Architecture

The registry system is designed around static asset distribution, making it compatible with providers like Cloudflare Workers, Vercel, and Netlify. A registry consists of a manifest (registry.jsonc), a collection of source files, and a build process that generates a standardized distribution structure.

Built Output Structure

When a registry is built, it generates a specific directory structure optimized for discovery and fetching:

Core Data Models

The system relies on several Zod-validated schemas to ensure data integrity and "fail-fast" behavior during the build and installation phases.

Registry Manifest

The registry.jsonc file is the source of truth for a registry. It defines the namespace, versioning, and the list of components included.

Field	Type	Description
name	string	Human-readable name of the registry.
namespace	string	Unique identifier for qualified component references (e.g., kdco).
version	string (semver)	The current version of the registry.
components	Array	List of component manifests.
opencode	string (semver)	Minimum OpenCode version requirement.

Sources: packages/cli/src/schemas/registry.ts:400-435, AGENTS.md:92-110

Component Manifest

Each component defines its type, required files, and dependencies.

Component Type	Purpose	File Format
ocx:skill	AI behavior instructions	Markdown (SKILL.md)
ocx:plugin	Code extending OpenCode	TypeScript (.ts)
ocx:agent	Specialized AI roles	Markdown (.md)
ocx:bundle	Collections of components	JSON

Sources: packages/cli/src/schemas/registry.ts:109-116, AGENTS.md:113-118

Registry Lifecycle Processes

1. Scaffolding and Initialization

Developers can create a new registry using the init --registry command. This fetches a template (typically from examples/registry-starter) and performs placeholder replacement for the namespace and author.

Sources: packages/cli/src/commands/init.ts:168-212

2. The Build Process

The buildRegistry function transforms source files into the distribution format. It enforces "Cargo-style" shorthand normalization, mapping simple paths like plugin/foo.ts to .opencode/plugin/foo.ts.

3. Installation and Dependency Resolution

When a user runs ocx add <namespace>/<component>, the system performs the following steps:

1. Resolution: Identifies all dependencies recursively across configured registries.
2. Pre-flight Checks: Verifies SHA-256 integrity hashes from the lockfile and checks for local file conflicts.
3. Atomic Installation: Fetches all files into memory and writes them only if no conflicts exist, ensuring a "fail-fast" outcome.
4. Configuration Merging: Deep-merges the component's opencode configuration block into the user's opencode.jsonc.

Sources: packages/cli/src/commands/add.ts:180-265, packages/cli/src/commands/add.ts:285-330

Security and Integrity

The registry system implements several layers of "Elegant Defense":

• Integrity Verification: The ocx.lock file stores SHA-256 hashes of component bundles. If a fetched bundle doesn't match the lockfile hash, an IntegrityError is thrown.
• Path Containment: During installation, target paths are verified to ensure they reside within the project root, preventing path traversal attacks.
• Conflict Detection: The system detects if a file at a target path was installed by a different component before overwriting.

Sources: packages/cli/src/commands/add.ts:245-275, packages/cli/src/commands/update.ts:255-270, AGENTS.md:21-45

Component Update Flow

Updates are handled by comparing the local hash stored in ocx.lock with the hash of the latest version available in the registry.

Command	Action
ocx update <name>	Checks specific component for changes.
ocx update --all	Scans all installed components for registry updates.
ocx update --dry-run	Previews changes without modifying the filesystem.

Sources: packages/cli/src/commands/update.ts:98-150

Summary

The OCX Registry System provides a robust, decentralized framework for managing AI extensions. By combining strict Zod schemas, atomic file operations, and a "Copy. Paste. Own." philosophy, it ensures that developers have full control over the code running in their AI environments while benefiting from the modularity of a package-managed ecosystem.