Registry and Marketplace

Cinatra ships with a shared marketplace and a per-instance registry. The marketplace is where you discover and install extensions — agents and skill packages — that other Cinatra instances have published. The registry is the npm-compatible Verdaccio (private to your instance or shared across instances) that stores the actual packages.

This document is the end-user reference for both. For the engineering shape of the lifecycle (handlers, audit tables, force-delete, the ExtensionOrigin record), see Extensions.

What you can install

Two kinds of extension are installable today:

Agent extensions — OAS Flow agents published as npm-style packages. Installing one creates an agent_templates row, registers any object types the agent declares, installs any skill bundles the package carries, and makes the agent reachable from the Agents sidebar and from any MCP client connected to your instance.
Skill extensions — SKILL.md packages from a GitHub release. Installing one persists a skill_packages row, populates the skills catalog, and triggers a skill-match recompute so the new skills are reachable by any agent whose match_when rules accept them.

Connector, asset, entity, and CMS handler kinds are not currently registered as separate extension types — they ship as workspace packages compiled into the platform.

The Marketplace screen

Administration → Marketplace (/administration/marketplace) is the install surface. Each row in the marketplace lists a package — its name, version, description, scope, and a status badge. The action button reflects the row’s current state in your workspace:

Button	When it appears
Install Now	Package is not installed locally
Update Now	Package is installed at an older version
Installed	Package is installed at the latest version (disabled CTA)
Restore	Package was archived (soft-uninstalled) and can be re-activated
Reinstall latest	Available in the Archived tab to bring a soft-uninstalled extension back at the latest registry version

When your instance has no remote registry connected yet, the marketplace empty-state CTA points to the registry-configuration tab at /administration/environment?tab=registries. Connecting a remote registry is the prerequisite for browsing anything other than packages you’ve published locally.

Public and private visibility

Every published extension carries a visibility on its origin record:

public — visible to every Cinatra instance reading the shared registry.
private — visible only to the publishing instance. The marketplace filters server-side: a private extension whose origin.scope does not match the reading instance’s vendor scope is dropped from the result set before render. This is a server-side regression-gated contract, not a UI affordance.

Private is the default for any new publish. Make a package public deliberately, when you want other tenants to install it.

Installing from GitHub releases (skill packages)

Administration → Extensions → Upload (/administration/extensions/upload) installs a skill package directly from a GitHub repository — no need to publish it to the marketplace first. The flow:

Paste a GitHub repo URL (https://github.com/<owner>/<repo>) or owner/repo shorthand.
The platform reads the repo’s release list and presents a release picker — pick the version you want.
If the repo is private, choose an authenticated GitHub connection from your Connectors area; public repos need no credentials.
Confirm. The platform fetches the release tarball, validates it, installs the skill_packages row, and runs a skill-match recompute.

Behind the scenes this calls the skills_packages_install_from_github MCP primitive. Admin-only.

The instance namespace

Every Cinatra instance picks a namespace during setup (under Administration → Instance). That namespace doubles as the npm scope used in every package this instance publishes — @<instance-namespace>/<extension-slug>. The namespace is the stable identity an instance presents to the shared marketplace.

A few invariants follow from this:

You cannot publish anything until your instance has a namespace.
The namespace is the basis for the server-side visibility filter — your own private extensions are visible to your instance because they share your namespace as origin.scope.
A reserved-substrings list prevents instances from claiming namespaces that conflict with the Cinatra-platform vendor scopes; the validator surfaces a specific error if a forbidden substring is detected.

Publishing your own extension

Publishing is admin-only.

For OAS Flow agents:

Author the agent (see Creating agents in chat for the chat-driven flow, or Developing agents for the file-driven flow).
Bump the agent’s package.json version.
Call the publish MCP primitive (agent_source_publish from chat, or trigger it from the agent’s screen). The platform runs the deterministic review gate first — a package that fails review cannot publish.
Pick a destination: private (your own registry, the default) or public (the shared marketplace).
The platform packs the tarball, resolves credentials from extension_destinations by destination ID, and pushes through the right topology adapter for your routingMode.

For skill packages:

Publish through your registry’s normal npm publish flow, or upload via Extensions → Upload as described above.

The package becomes visible to the chosen audience and installable through the normal marketplace flow.

Promotion (private → public)

A private extension can be promoted to public. The action is exposed in the row-level menu on /administration/extensions and is implemented by promoteExtensionToPublicAction. It:

Requires an admin session.
Refuses if the extension is already public.
Republishes the package to the public destination at its current version.
Updates the persisted origin.visibility to "public".
Fire-and-forget writes a promote row to audit_events (with resourceType: "extension_registry").

Promotion is one-way today. The reverse direction (public → private) is intentionally blocked; the demotion button is rendered disabled with a locked tooltip explaining the limit. There is no half-built demotion flow to fall back on — if you genuinely need to retract a public extension, contact the operations side.

Who can do what

Action	Role required
Browse Marketplace	Admin
Install / update an extension	Admin
Upload a skill package from GitHub	Admin
Archive / restore an extension	Admin
Force-delete an extension (DB + on-disk only — does NOT touch the registry; audited)	Admin, with explicit `confirmDestructive: true`
Unpublish / delete one registry version (`extensions_registry_unpublish` / `extensions_registry_delete`, kind-agnostic)	Admin
Plan a full purge (`extensions_purge` — dry-run blast radius + digest)	Admin
Fully purge an extension everywhere (all registry versions + DB + disk)	Operator only — the human-origin `cinatra extensions purge` CLI (loopback, dev-mode); NOT an MCP/model action
Publish a package	Admin
Promote a private extension to public	Admin
Run an installed agent	Any user whose role is permitted by the agent’s permissions (see below)

The platform also has a generic permissions surface keyed by extension kind — agent_template, agent_run, skill_package, and skill — with co-owner support so an extension owner can grant another user co-owner access without making them an organization admin. The access level granted to non-co-owners (read, run, share) is governed by the per-resource access policy. Per-skill records let an individual skill carry a tighter or wider policy than its parent package. See Security for the model and Workspace features for where the permissions surfaces live in the UI.

Where to go next

The engineering side of the lifecycle (handlers, dispatcher, audit tables): Extensions
How agents authored elsewhere arrive into Cinatra: Developing agents
The open-standards story for portability: Open standards in Cinatra