Registry Protocol

Overview

This document specifies the HTTP API that OCX-compatible registries must implement. Registries serve component metadata and files as static JSON endpoints.

V2 Changes: Registry targets are now root-relative (no .opencode/ prefix required). The OCX CLI handles path resolution based on component type.

Discovery (Optional)

GET /.well-known/ocx.json

Optional discovery metadata for clients that support a /.well-known/ocx.json lookup. Response:

{
  "registry": "/index.json"
}

Field	Type	Description
`registry`	string	Path to the registry index endpoint

If not provided, clients must be configured with the full registry URL.

ocx registry add currently validates registries by requesting <registry-url>/index.json directly. It does not resolve /.well-known/ocx.json during add flows.

Required Endpoints

Registry Index

GET /index.json

Returns registry metadata and a list of available components. Response:

{
  "$schema": "https://ocx.kdco.dev/schemas/v2/registry.json",
  "name": "My Registry",
  "version": "1.0.0",
  "author": "Your Name",
  "components": [
    {
      "name": "my-skill",
      "type": "skill",
      "description": "A helpful skill"
    }
  ]
}

Field	Type	Required	Description
`$schema`	string	Conditional	Recommended for v2 registries; when present for OCX CLI-supported manifests, must be `https://ocx.kdco.dev/schemas/v2/registry.json`
`name`	string	No	Human-readable registry name (emitted by `ocx build`)
`version`	string	No	Registry version metadata (emitted by `ocx build`)
`author`	string	Yes	Registry author or organization
`components`	array	Yes	List of available components

Component summaries inside components[] use this shape:

Field	Type	Required
`name`	string	Yes
`type`	string	Yes
`description`	string	Yes

namespace and per-component version are not part of the runtime-required summary contract.

For v2 registries, publish $schema: "https://ocx.kdco.dev/schemas/v2/registry.json". If $schema is missing (or uses the unversioned legacy URL), OCX CLI treats the payload as legacy v1 compatibility mode.

Component resolution uses the configured alias from ocx registry add --name <alias> (for <alias>/<component> refs), not any registry-declared namespace field.

Component Packument

GET /components/{name}.json

Returns full component metadata in npm-style packument format. Response:

{
  "name": "my-skill",
  "dist-tags": {
    "latest": "1.0.0"
  },
  "versions": {
    "1.0.0": {
      "name": "my-skill",
      "type": "skill",
      "version": "1.0.0",
      "description": "A helpful skill",
      "files": [
        {
          "path": "SKILL.md",
          "target": "skills/my-skill/SKILL.md"
        }
      ],
      "dependencies": [],
      "opencode": {}
    }
  }
}

Field	Type	Description
`name`	string	Component identifier
`dist-tags`	object	Version aliases (`latest` required)
`versions`	object	Map of version string to component manifest

File Content

GET /components/{name}/{path}

Returns raw file content for installation.

Path	Content-Type
`*.md`	`text/markdown`
`*.ts`	`text/typescript`
`*.json`	`application/json`
Other	`text/plain`

Component Types

Type	Common Location	Description
`skill`	`skills/{name}/`	AI behavior instructions
`plugin`	`plugins/`	OpenCode plugins
`agent`	`agents/`	Custom agent definitions
`command`	`commands/`	Custom CLI commands
`tool`	`tools/`	Custom tools
`bundle`	(varies)	Meta-package grouping other components
`profile`	`~/.config/opencode/profiles/{name}/`	Shareable profile configuration

Targets in registry files are root-relative. The OCX CLI resolves them to the appropriate .opencode/ subdirectory based on component type.

Blocked Paths

Registry components cannot target these paths:

.ocx/ — OCX state and receipt
ocx.jsonc — OCX configuration
package.json — Package manifest
.git/ — Git internals
.env — Environment secrets
node_modules/ — Dependencies

Additional Security Constraints:

Absolute paths (starting with / or drive letters like C:) are rejected
Path traversal sequences (../, ..\\) are rejected
Null bytes and control characters are rejected

Minimal Compliant Registry

A registry with a single skill needs three files:

/index.json
/components/my-skill.json
/components/my-skill/SKILL.md

/index.json:

{
  "$schema": "https://ocx.kdco.dev/schemas/v2/registry.json",
  "name": "Minimal Registry",
  "version": "1.0.0",
  "author": "Your Name",
  "components": [
    {
      "name": "my-skill",
      "type": "skill",
      "description": "A helpful skill"
    }
  ]
}

/components/my-skill.json:

{
  "name": "my-skill",
  "dist-tags": { "latest": "1.0.0" },
  "versions": {
    "1.0.0": {
      "name": "my-skill",
      "type": "skill",
      "version": "1.0.0",
      "description": "A helpful skill",
      "files": [{ "path": "SKILL.md" }]
    }
  }
}

Hosting Options

Platform	Approach
Cloudflare Workers	Static assets from `dist/` directory
GitHub Pages	Pre-build with `ocx build`, serve `dist/`
Vercel / Netlify	Pre-build with `ocx build`, serve `dist/`
Any HTTP server	Serve required endpoints

Getting Started

Profiles

CLI

Registries

Reference

Guides

Integrations

Enterprise

Security

Overview

Discovery (Optional)

Required Endpoints

Registry Index

Component Packument

File Content

Component Types

Blocked Paths

Minimal Compliant Registry

Hosting Options

See Also

​Overview

​Discovery (Optional)

​Required Endpoints

​Registry Index

​Component Packument

​File Content

​Component Types

​Blocked Paths

​Minimal Compliant Registry

​Hosting Options

​See Also

Overview

Discovery (Optional)

Required Endpoints

Registry Index

Component Packument

File Content

Component Types

Blocked Paths

Minimal Compliant Registry

Hosting Options

See Also