Skip to main content

​
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"
}
FieldTypeDescription
registrystringPath 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"
    }
  ]
}
FieldTypeRequiredDescription
$schemastringConditionalRecommended for v2 registries; when present for OCX CLI-supported manifests, must be https://ocx.kdco.dev/schemas/v2/registry.json
namestringNoHuman-readable registry name (emitted by ocx build)
versionstringNoRegistry version metadata (emitted by ocx build)
authorstringYesRegistry author or organization
componentsarrayYesList of available components
Component summaries inside components[] use this shape:
FieldTypeRequired
namestringYes
typestringYes
descriptionstringYes
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": {}
    }
  }
}
FieldTypeDescription
namestringComponent identifier
dist-tagsobjectVersion aliases (latest required)
versionsobjectMap of version string to component manifest

​
File Content

GET /components/{name}/{path}
Returns raw file content for installation.
PathContent-Type
*.mdtext/markdown
*.tstext/typescript
*.jsonapplication/json
Othertext/plain

​
Component Types

TypeCommon LocationDescription
skillskills/{name}/AI behavior instructions
pluginplugins/OpenCode plugins
agentagents/Custom agent definitions
commandcommands/Custom CLI commands
tooltools/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

PlatformApproach
Cloudflare WorkersStatic assets from dist/ directory
GitHub PagesPre-build with ocx build, serve dist/
Vercel / NetlifyPre-build with ocx build, serve dist/
Any HTTP serverServe required endpoints

​
See Also