core/docs/PACKAGE-REGISTRY.md

Package Registry

The package registry lets admins browse and install packages from an external JSON index — a lightweight alternative to manually uploading .pkg files.

Registry JSON Format

The registry is a static JSON file matching the RegistryResponse struct:

{
  "packages": [
    {
      "id": "notes",
      "title": "Notes",
      "version": "0.8.0",
      "description": "Markdown notes with backlinks and graph view",
      "author": "switchboard",
      "type": "extension",
      "tier": "core",
      "download_url": "https://cdn.example.com/pkg/notes.pkg",
      "size": 48200,
      "updated_at": "2026-03-20T00:00:00Z"
    }
  ]
}

Required Fields

Field	Description
id	Package identifier (matches manifest.json)
title	Display name
version	Semver version string
description	Short description
download_url	HTTPS URL to the .pkg file (must be HTTPS)

Optional Fields

Field	Description
author	Package author
type	extension or library
tier	core, official, or community
size	File size in bytes
updated_at	ISO 8601 timestamp of last update

Configuring the Registry URL

Via Admin UI

Navigate to Admin > Settings > Package Registry and enter the registry URL.

Via API

curl -X PUT /api/v1/admin/settings/package_registry \
  -H "Content-Type: application/json" \
  -d '{"value": {"url": "https://cdn.example.com/pkg/registry.json"}}'

Generating a Registry

Use scripts/generate-registry.sh to build a registry.json from a directory of .pkg files:

# Default: reads dist/, uses placeholder base URL
./scripts/generate-registry.sh

# Custom directory and base URL
./scripts/generate-registry.sh ./my-packages https://cdn.example.com/pkg > registry.json

Requirements: jq, unzip, and stat (GNU or BSD).

Self-Hosting

Any HTTPS-capable file server works. Upload your .pkg files and the generated registry.json to the same directory, then point the admin setting to the registry.json URL.

Example with a static file server:

/var/www/packages/
  registry.json
  notes.pkg
  chat.pkg
  chat-core.pkg

The registry is fetched and cached for 5 minutes on each browse request.