Custom Registries

Host and distribute custom agent skills and context bundles with custom registries

BRV Hub supports custom registries beyond the official hub.byterover.dev. Create your own custom private registry to distribute internal skills and bundles across your team, then register it with the BRV CLI to browse and install entries alongside the official catalog.

All registries are fetched in parallel with graceful degradation — if a private registry is unreachable, others continue to work normally.

NOTE

The official registry is always included and cannot be removed.

Hosting Your Own Registry

The BRV Hub repository is an open-source, zero-backend registry template. Clone it to host your own private registry of agent skills and context bundles, using GitHub Actions for validation and automatic registry.json generation.

NOTE

The BRV Hub template is MIT-licensed. You can clone it into a private repository for internal use.

Step-by-Step Setup

Step 1: Clone the BRV Hub template

For a public registry, fork the repo directly on GitHub and clone it:

bash

gh repo fork campfirein/brv-hub --clone --remote
cd brv-hub
npm install

For a private registry, clone the template and push to a new private repo (GitHub does not allow forking a public repo into a private repo):

bash

git clone https://github.com/campfirein/brv-hub.git my-hub
cd my-hub
rm -rf .git
git init
gh repo create your-org/my-hub --private --source . --push
npm install

TIP

Alternatively, use GitHub's Import repository feature to import https://github.com/campfirein/brv-hub into a new private repo.

Step 2: Configure your registry URLs

Open scripts/update-registry.js. The official hub uses proxy routes (/r/ for downloads, /v/ for viewing) that don't exist on GitHub, GitLab, or self-hosted platforms. You need to update the base URL and the URL patterns to match your hosting platform.

Line 5 — change the base URL constant:

javascript

// Before (official hub)
const HUB_BASE_URL = "https://hub.byterover.dev";

// After — GitHub
const HUB_BASE_URL = "https://github.com/your-org/your-hub/tree/main";

// After — GitLab
const HUB_BASE_URL = "https://gitlab.com/your-org/your-hub/-/tree/main";

// After — self-hosted
const HUB_BASE_URL = "https://registry.yourcompany.com";

For GitHub and GitLab, add a second constant for raw content URLs right after HUB_BASE_URL:

javascript

// GitHub:
const CONTENT_BASE_URL = "https://raw.githubusercontent.com/your-org/your-hub/main";

// GitLab:
const CONTENT_BASE_URL = "https://gitlab.com/your-org/your-hub/-/raw/main";

Then update the 4 URL constructions to remove the /r/ and /v/ route prefixes:

javascript

// Line 77 — file_tree URLs (downloads)
// Before:
url: `${HUB_BASE_URL}/r/${entryPath}/${f}`
// After:
url: `${CONTENT_BASE_URL}/${entryPath}/${f}`

// Line 94 — path_url (browsable link to the entry)
// Before:
path_url: `${HUB_BASE_URL}/${entryId}`
// After:
path_url: `${HUB_BASE_URL}/${entryPath}`

// Line 95 — manifest_url
// Before:
manifest_url: `${HUB_BASE_URL}/v/${entryPath}/manifest.json`
// After:
manifest_url: `${CONTENT_BASE_URL}/${entryPath}/manifest.json`

// Line 96 — readme_url
// Before:
readme_url: `${HUB_BASE_URL}/v/${entryPath}/README.md`
// After:
readme_url: `${CONTENT_BASE_URL}/${entryPath}/README.md`

NOTE

For self-hosted registries that serve files directly (no separate raw content domain), set both HUB_BASE_URL and CONTENT_BASE_URL to the same value, or use HUB_BASE_URL everywhere and skip the second constant.

WARNING

The file_tree, manifest_url, and readme_url values must point to URLs that return raw file content, not HTML pages. The BRV CLI uses these URLs to download files directly.

Step 3: Remove example entries

bash

rm -rf skills/*
rm -rf bundles/*

Step 4: Add your own skills or bundles

Create a directory for each entry with the required files:

skills/my-internal-skill/
├── manifest.json    # Entry metadata
├── README.md        # Usage instructions
└── SKILL.md         # Skill workflow content

bundles/my-context-pack/
├── manifest.json    # Entry metadata
├── README.md        # Usage instructions
└── context.md       # Context content

Create a manifest.json for each entry:

json

{
  "id": "my-internal-skill",
  "name": "My Internal Skill",
  "version": "1.0.0",
  "description": "An internal skill for our team's code review workflow",
  "type": "agent-skill",
  "author": { "name": "Your Team" },
  "tags": ["internal", "review"],
  "category": "code-quality"
}

TIP

See the manifest specification for all available fields including long_description, dependencies, and metadata.

Step 5: Validate locally

bash

npm run validate

Validation checks:

JSON Schema compliance for all manifests
Directory name matches the id field
Entry type matches parent directory (agent-skill → skills/, bundle → bundles/)
Required files are present (README.md, SKILL.md or context.md)
id and name are globally unique across all entries

Step 6: Generate and push the registry

The template includes two GitHub Actions workflows:

validate-pr.yml — validates every PR that touches skills/ or bundles/
update-registry.yml — regenerates registry.json automatically on push to main

Once your changes are merged to main, the registry updates automatically.

To generate the registry manually instead:

bash

npm run update-registry
git add registry.json
git commit -m "chore: update registry"
git push

See GitHub Actions Setup below for configuring the automated workflows.

Step 7: Register with BRV CLI

Connect your private registry to the BRV CLI so you can browse and install entries.

NOTE

For GitHub private repos, you need a Personal Access Token with repo scope (classic) or Contents: Read-only permission (fine-grained). See Creating a personal access token on GitHub Docs.

bash

# GitHub private repo (using Personal Access Token)
brv hub registry add my-team \
  --url https://raw.githubusercontent.com/your-org/your-hub/main/registry.json \
  --auth-scheme token \
  --token ghp_your_personal_access_token

bash

# Self-hosted (no authentication)
brv hub registry add my-team \
  --url https://registry.yourcompany.com/registry.json

bash

# GitLab private repo
brv hub registry add my-team \
  --url https://gitlab.com/your-org/your-hub/-/raw/main/registry.json \
  --auth-scheme custom-header \
  --header-name PRIVATE-TOKEN \
  --token glpat-your_token

Or use the TUI equivalent:

/hub registry add my-team --url <url> --token <token>

TIP

See Authentication Schemes for all supported auth methods and CLI Commands for the full registry add reference.

Step 8: Verify and install

bash

# Verify your registry appears and is reachable
brv hub registry list

# List entries — your private entries appear alongside official ones
brv hub list

# Install a skill from your private registry
brv hub install my-internal-skill --registry my-team --agent "Claude Code"

Entry File Requirements

Type	Directory	Required Files
`agent-skill`	`skills/<id>/`	`manifest.json`, `README.md`, `SKILL.md`
`bundle`	`bundles/<id>/`	`manifest.json`, `README.md`, `context.md`

NOTE

The directory name must match the id field in manifest.json exactly. Use kebab-case, 3–64 characters, no consecutive hyphens.

Manifest Reference

Field	Type	Description
`id`	string	Kebab-case identifier matching the directory name (3–64 chars)
`name`	string	Human-readable name (3–100 chars, globally unique)
`version`	string	Semantic version (e.g., `1.0.0`)
`description`	string	What the entry does and when to use it (max 1024 chars)
`type`	string	`agent-skill` or `bundle`
`author`	object	`{ "name": "..." }` (required); optional `email`, `url`
`tags`	array	1–10 search tags
`category`	string	One of the valid categories below

Valid categories: productivity, code-quality, testing, documentation, refactoring, debugging, deployment, analysis, security, learning

TIP

See the full manifest specification for optional fields like long_description, license, dependencies, and metadata.

Hosting Options

Platform	Base URL Pattern	Auth Scheme	`registry add` Flags
GitHub (private)	`https://raw.githubusercontent.com/org/repo/main`	`token`	`--auth-scheme token --token ghp_xxx`
GitLab (private)	`https://gitlab.com/org/repo/-/raw/main`	`custom-header`	`--auth-scheme custom-header --header-name PRIVATE-TOKEN --token glpat-xxx`
Self-hosted	`https://registry.yourcompany.com`	`bearer` or `none`	`--token secret` or no auth flags
GitHub Pages	`https://org.github.io/repo`	`none`	No auth flags (public only; private Pages requires GitHub Enterprise)

GitHub Actions Setup

The template ships with two workflows that automate validation and registry generation. To enable them:

Step 1: Create a Personal Access Token

Go to GitHub > Settings > Developer settings > Personal access tokens > Fine-grained tokens. Grant Contents: Read and write permission scoped to your registry repository.

Step 2: Add as repository secret

In your registry repo, go to Settings > Secrets and variables > Actions and create a secret named PAT_TOKEN with your token value.

WARNING

The PAT_TOKEN secret is required because the default GITHUB_TOKEN cannot trigger subsequent workflows. Without it, the update-registry.yml workflow will fail to push the generated registry.json.

CLI Commands

`brv hub registry list`

List all configured registries with their connection status and entry counts.

bash

brv hub registry list [OPTIONS]

Flag	Description	Default
`-f, --format <format>`	Output format: `text` or `json`	`text`

The output includes each registry's name, URL, authentication status, and entry count (or error message if unreachable).

`brv hub registry add <name>`

Add a new custom registry.

bash

brv hub registry add <name> [OPTIONS]

Argument / Flag	Description	Required
`name`	Registry name (used in `--registry` flag)	Yes
`-u, --url <url>`	Registry URL	Yes
`-t, --token <token>`	Auth token for private registry	No
`-s, --auth-scheme <scheme>`	Authentication scheme	No
`--header-name <name>`	Custom header name (for `custom-header` scheme)	No
`-f, --format <format>`	Output format: `text` or `json`	No

bash

# Public registry (no auth)
brv hub registry add myco --url https://example.com/registry.json

# Bearer token (default when --token is provided)
brv hub registry add myco --url https://example.com/registry.json --token secret123

# GitHub personal access token
brv hub registry add ghrepo \
  --url https://raw.githubusercontent.com/org/repo/main/registry.json \
  --auth-scheme token \
  --token ghp_xxx

# GitLab private token
brv hub registry add gitlab \
  --url https://gitlab.com/org/repo/-/raw/main/registry.json \
  --auth-scheme custom-header \
  --header-name PRIVATE-TOKEN \
  --token glpat-xxx

# Basic auth
brv hub registry add internal \
  --url https://internal.example.com/registry.json \
  --auth-scheme basic \
  --token user:password

WARNING

The following registry names are reserved and cannot be used: brv, byterover, campfire, campfirein, official.

`brv hub registry remove <name>`

Remove a custom registry and its stored credentials (if private).

bash

brv hub registry remove <name>

bash

brv hub registry remove myco

Both the registry configuration and any stored authentication token are removed.

Authentication Schemes

Scheme	HTTP Header Sent	Use Case
`bearer`	`Authorization: Bearer <token>`	Most APIs (default when `--token` is provided)
`token`	`Authorization: token <token>`	GitHub personal access tokens
`basic`	`Authorization: Basic <base64>`	HTTP basic auth
`custom-header`	`<header-name>: <token>`	GitLab, custom APIs
`none`	(no header)	Public registries

Token Storage

Authentication tokens are stored using file-based AES-256-GCM encryption with the following storage locations:

macOS — ~/Library/Application Support/brv/
Linux — $XDG_DATA_HOME/brv/ (defaults to ~/.local/share/brv/)
Windows — %LOCALAPPDATA%/brv/

Encryption keys and credential files are created with 0600 permissions (owner read/write only). The encryption key is regenerated on every write operation.

Registry configurations (name, URL, auth scheme — but not tokens) are stored in hub-registries.json within the same data directory.

Registry Format

A registry is a JSON file containing a version string and an entries array. Each entry describes a skill or bundle with its metadata and downloadable files.

json

{
  "version": "1.0.0",
  "entries": [
    {
      "id": "my-skill",
      "name": "My Custom Skill",
      "version": "1.0.0",
      "description": "A custom agent skill for your team",
      "type": "agent-skill",
      "author": { "name": "Your Team" },
      "tags": ["custom"],
      "category": "productivity",
      "file_tree": [
        { "name": "SKILL.md", "url": "https://example.com/skills/my-skill/SKILL.md" }
      ],
      "readme_url": "https://example.com/skills/my-skill/README.md",
      "manifest_url": "https://example.com/skills/my-skill/manifest.json",
      "path_url": "https://example.com/skills/my-skill"
    }
  ]
}

TIP

See the BRV Hub repository for the full manifest specification, validation schema, and contribution guide.

Multi-Registry Behavior

When multiple registries are configured:

Entries from all registries are merged and displayed together in brv hub list and the /hub TUI.
If the same entry ID exists in multiple registries, the install command requires the --registry <name> flag to disambiguate.
Failed registries are silently skipped — one unreachable registry does not block access to others.
Registry data is cached for 5 minutes per registry to reduce network requests.

Troubleshooting

Registry validation fails when adding

The registry URL must be reachable and return valid JSON during brv hub registry add. Verify that:

* The URL points to a valid registry JSON file
* Authentication credentials are correct (if the registry is private)
* The server is reachable from your network

Entry exists in multiple registries

When an entry ID appears in more than one registry, use the --registry flag to specify which one to install from:

```bash
brv hub install my-skill --registry myco --agent "Claude Code"
```

Authentication failed (HTTP 401/403)

Verify that:

* The token is correct and not expired
* The `--auth-scheme` matches what the server expects
* For `custom-header`, the `--header-name` is correct (e.g., `PRIVATE-TOKEN` for GitLab)

Re-add the registry with updated credentials:

```bash
brv hub registry remove myco
brv hub registry add myco --url https://example.com/registry.json --token new-token
```

Cannot use reserved registry name

The names brv, byterover, campfire, campfirein, and official are reserved. Choose a different name for your registry.

Registry generation fails in GitHub Actions

Verify that:

* The `PAT_TOKEN` repository secret exists under **Settings > Secrets and variables > Actions**
* The token has **Contents: Read and write** permission scoped to the repository
* The token has not expired

Check the **Actions** tab in your repository for workflow run logs.

Private registry returns 404 for file downloads

Verify that:

* The `HUB_BASE_URL` in `scripts/update-registry.js` matches the actual URL where your files are served
* The branch name in the URL is correct (e.g., `main` vs `master`)
* The auth token used with `brv hub registry add` has read access to the repository

Re-generate the registry after fixing the base URL:

```bash
npm run update-registry
```

Next Steps

BRV Hub Overview — Browse and install skills and bundles from the hub
Contributing — Submit your own skills and bundles to the community hub

Custom Registries ​

Hosting Your Own Registry ​

Step-by-Step Setup ​

Step 1: Clone the BRV Hub template ​

Step 2: Configure your registry URLs ​

Step 3: Remove example entries ​

Step 4: Add your own skills or bundles ​

Step 5: Validate locally ​

Step 6: Generate and push the registry ​

Step 7: Register with BRV CLI ​

Step 8: Verify and install ​

Entry File Requirements ​

Manifest Reference ​

Hosting Options ​

GitHub Actions Setup ​

Step 1: Create a Personal Access Token ​

Step 2: Add as repository secret ​

CLI Commands ​

brv hub registry list ​

brv hub registry add &lt;name&gt; ​

brv hub registry remove &lt;name&gt; ​

Authentication Schemes ​

Token Storage ​

Registry Format ​

Multi-Registry Behavior ​

Troubleshooting ​

Registry validation fails when adding ​

Entry exists in multiple registries ​

Authentication failed (HTTP 401/403) ​

Cannot use reserved registry name ​

Registry generation fails in GitHub Actions ​

Private registry returns 404 for file downloads ​

Next Steps ​

Custom Registries

Hosting Your Own Registry

Step-by-Step Setup

Step 1: Clone the BRV Hub template

Step 2: Configure your registry URLs

Step 3: Remove example entries

Step 4: Add your own skills or bundles

Step 5: Validate locally

Step 6: Generate and push the registry

Step 7: Register with BRV CLI

Step 8: Verify and install

Entry File Requirements

Manifest Reference

Hosting Options

GitHub Actions Setup

Step 1: Create a Personal Access Token

Step 2: Add as repository secret

CLI Commands

`brv hub registry list`

`brv hub registry add <name>`

`brv hub registry remove <name>`

Authentication Schemes

Token Storage

Registry Format

Multi-Registry Behavior

Troubleshooting

Registry validation fails when adding

Entry exists in multiple registries

Authentication failed (HTTP 401/403)

Cannot use reserved registry name

Registry generation fails in GitHub Actions

Private registry returns 404 for file downloads

Next Steps