> ## Documentation Index
> Fetch the complete documentation index at: https://ocx.kdco.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Registry Protocol

> HTTP API specification that OCX-compatible registries must implement

## Overview

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

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

## Discovery (Optional)

```
GET /.well-known/ocx.json
```

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

**Response:**

```json theme={null}
{
  "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.

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

## Required Endpoints

### Registry Index

```
GET /index.json
```

Returns registry metadata and a list of available components.

**Response:**

```json theme={null}
{
  "$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.

<Note>
  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.
</Note>

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

### Component Packument

```
GET /components/{name}.json
```

Returns full component metadata in npm-style packument format.

**Response:**

```json theme={null}
{
  "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`:**

```json theme={null}
{
  "$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`:**

```json theme={null}
{
  "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                  |

## See Also

* [Creating Registries](/docs/registries/create) — Guide to building your own registry.
* [ocx build](/docs/cli/build) — CLI command for building registries.
* [Enterprise Overview](/docs/enterprise/overview) — Locking, versioning, and integrity verification.