Registry API & Workers

Relevant source files

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

• packages/cli/src/lib/build-registry.ts
• packages/cli/src/commands/init.ts
• packages/cli/tests/build.test.ts
• examples/registry-starter/AGENTS.md
• examples/registry-starter/README.md
• CONTRIBUTING.md

The Registry system in OCX is a "copy-and-own" infrastructure designed to distribute reusable AI components, including skills, plugins, agents, and bundles. It functions as a collection of static assets that can be served via modern edge platforms like Cloudflare Workers, Vercel, or Netlify, enabling a decentralized approach to extending OpenCode functionality.

Sources: CONTRIBUTING.md:7-10, examples/registry-starter/README.md:3-13, examples/registry-starter/AGENTS.md:7-14

Registry Architecture & Discovery

The OCX registry is fundamentally a set of structured JSON files and source assets generated from a source repository. The architecture relies on a well-defined directory structure that includes a discovery endpoint to allow CLI tools to locate the registry index.

Discovery Mechanism

Every OCX registry exposes a discovery endpoint at .well-known/ocx.json. This file contains a single reference pointing to the main registry index, typically /index.json. This standardized path allows the OCX CLI to bootstrap its connection to the registry using only the base URL.

The diagram above illustrates the resolution path from a base URL to specific component assets.

Sources: packages/cli/src/lib/build-registry.ts:133-137, packages/cli/tests/build.test.ts:70-75

Build Process

The transformation of source components into a deployable registry is handled by the buildRegistry library function and the ocx build command. This process validates the registry manifest and generates a "packument" for every component.

Build Logic Flow

1. Manifest Resolution: The builder looks for registry.jsonc or registry.json in the source directory.
2. Schema Validation: The manifest is validated against the registrySchema to ensure valid namespaces, versions, and component definitions.
3. Packument Generation: For each component, a versioned JSON manifest (packument) is created in the components/ directory.
4. Asset Distribution: Source files (e.g., .ts, .md) are copied into component-specific subdirectories within the output folder.
5. Index Generation: A global index.json is created containing metadata for the entire registry and a summary of all components.

This sequence shows the transformation of local source files into a structured distribution format.

Sources: packages/cli/src/lib/build-registry.ts:47-131, packages/cli/tests/build.test.ts:19-60

Registry Manifest Configuration

The registry.jsonc file serves as the primary configuration for a registry. It defines the namespace, which acts as a prefix for all components (e.g., ocx add namespace/component).

Manifest Fields

Field	Type	Description
name	string	Human-readable name of the registry.
namespace	string	URL-safe identifier used for CLI references.
version	string	Semantic version of the registry.
author	string	Maintainer/Author information.
components	Array	List of component definitions including type, name, and file mappings.

Sources: examples/registry-starter/AGENTS.md:73-95, packages/cli/src/lib/build-registry.ts:111-125, CONTRIBUTING.md:16-41

Component Types & Structure

OCX supports various component types, each represented differently within the registry structure.

Supported Types

• ocx:skill: AI behavior instructions, typically stored as SKILL.md.
• ocx:plugin: TypeScript-based extensions that hook into OpenCode lifecycles.
• ocx:agent: Role definitions in Markdown format.
• ocx:bundle: Collections of other components for bulk installation.

Storage Layout

The built registry follows a strict layout to ensure compatibility with the OCX fetcher:

• index.json: Registry metadata and component list.
• .well-known/ocx.json: Discovery metadata.
• components/[name].json: The "packument" containing version history for a component.
• components/[name]/[file_path]: The raw source assets (e.g., index.ts, SKILL.md).

Sources: examples/registry-starter/AGENTS.md:99-106, packages/cli/src/lib/build-registry.ts:81-105

Deployment & Worker Integration

Registries are designed to be deployed as static sites or via Edge Workers. The "Registry Starter" provides configurations for major platforms.

Platform Support

Platform	Configuration File	Command
Cloudflare Workers	wrangler.jsonc	bun run deploy / wrangler deploy
Vercel	vercel.json	Push to GitHub / vercel
Netlify	netlify.toml	Push to GitHub / netlify deploy

The Cloudflare Workers implementation typically serves the dist/ directory as static assets. Developers can use the ocx init --registry command to scaffold a new registry project including these deployment configurations.

Sources: examples/registry-starter/README.md:5-24, packages/cli/src/commands/init.ts:182-210

Summary

The Registry API & Workers system provides a robust, schema-validated pipeline for distributing OpenCode extensions. By combining a static-first file structure with standardized discovery through .well-known/ocx.json, it enables developers to host their own AI component registries on edge infrastructure with minimal overhead. The build process ensures that all assets are correctly versioned and accessible to the OCX CLI.