Host a registry

A registry lets people discover releases and install or update them from a known source. A static HTTPS host can serve discovery, a catalog and artifacts without a server-side application. Larger registries can expose paged catalogs and direct release lookup behind the same base address.

Prepare files in Hay

Open Plugins / Share & publish, name the registry, choose the installed plugins to include, and select Prepare registry files. Choose a local parent folder.

Hay writes a new hay-registry-* directory containing:

hay-registry-…/
  .well-known/
    hay-registry.json
  index.json
  artifacts/
    <sha256>.hay-plugin.json
  README.md

The export includes installed code and manifests only. Workspace records and grants remain on the Mac. Nothing has been uploaded.

Build from source projects

For repeatable releases, use the generic tooling from the Hay app repository. Build each plugin first with the SDK, then create a catalog.json in your registry project:

{
  "name": "Team tools",
  "plugins": [{
    "project": "../little-notes",
    "artifact": "../little-notes/dist/example.little-notes-0.1.0.hay-plugin.json"
  }]
}

Paths are relative to the registry directory. Each artifact must be inside its source project’s dist directory.

node /path/to/hay/packages/sdk/build-plugin.mjs /path/to/little-notes
node /path/to/hay/registry/build.mjs /path/to/registry
node /path/to/hay/registry/serve.mjs /path/to/registry/dist

Connect the local server at http://127.0.0.1:4716/. Set HAY_REGISTRY_PORT for another port. It binds only to loopback; it is a development server, not a public host.

Put it online

Upload .well-known/hay-registry.json, index.json and artifacts/ together, including the dot directory. The descriptor points to index.json. Preserve their relative paths; hosting under a nested prefix such as /team/ is supported. Configure the host to return JSON files directly, without redirects, login pages, or HTML fallbacks.

In Hay, connect a base address under Plugins / Registry, for example plugins.example.com or https://plugins.example.com/team/. Use your actual domain; these examples do not host a registry. Hay discovers the catalog and remembers saved sources for switching. Existing saved /index.json addresses normalize to the parent base, with equivalent historical provenance recognized for updates and restoration.

For older static hosts without discovery, only an HTTP 404 or 410 for the descriptor triggers a fallback to index.json. A login page, redirect or invalid JSON is an error. Static indexes retain a 100-release / 1,000,000-byte bound. For larger catalogs, implement paged discovery and direct release lookup; current client browsing remains bounded.

Test the registry in a fresh workspace: browse, install one release, approve installation, grant access, and open a task. Verify that a changed byte or wrong digest is refused.

Release updates

Increase the plugin’s version, build a new artifact, and add a new ID/version entry. Retain previously released entries and artifacts. Upload artifacts before changing the index, so the catalog never points at a missing file.

A newly prepared folder includes only the installed versions selected for that export. Before updating an existing hosted registry, merge those new entries and artifacts with its retained release history. Do not replace the old index with a fresh export and accidentally drop earlier releases.

A newer version from an installed plugin’s recorded registry can update after review if its old view IDs remain available. Records are preserved and all capabilities reset. Downgrades, foreign-source replacements, changed bytes at the same version, and migrations that remove views are not silent updates.

Hay’s catalog and publisher accounts

The default Hay registry address is plugins.hay.so. Its public discovery, catalog, release metadata and artifacts can be read without an account token. The desktop app itself requires a Hay account.

For direct publication, Hay’s account/API service authenticates the user and checks ownership of a personal publisher handle. Read publish to Hay for the release workflow and publisher API for its server contract. Account credentials go only to the account/API origin and the signed-in account’s exact personal registry base. Public and custom registry downloads remain unauthenticated reads. The marketplace adds human browsing, search and explicit install links without handling account tokens.

A static custom registry needs only its discovery file, version 1 catalog and artifacts. It does not need to implement Hay account login. Account-backed publishing adds namespace authorization; it does not turn a digest into a code-safety guarantee.

New account/API requests use https://app.hay.so; the public registry origin is unchanged. Legacy account APIs remain served directly for older clients. Earlier live inbox-code, publication and revocation checks used the legacy account origin and shared D1 storage; they do not by themselves verify the new origin. The first public entry is Documents 0.1.1, ID halil.documents. Hay’s production downloader and package installer verified its artifact and installed it into a disposable fresh workspace with empty records and zero grants. The operator record describes the exact evidence and UI-test boundary.