Application Marketplace

The Cozystack marketplace lets an administrator extend the built-in application catalog with applications published in external repositories. Connecting a repository to a cluster makes its applications available to install; once one is installed, it appears in the same dashboard catalog and behaves like the standard managed applications platform users already know.

A repository is a self-contained, versioned bundle published as an OCI artifact. It is authored and validated with the cozypkg CLI, connected to a cluster with a single command (or from the dashboard), and, optionally, listed in a community index so operators can discover it.

How it works

A marketplace repository ships one or more PackageSource resources. Each PackageSource declares variants and components, and every component is a Helm chart. A user-installable application takes two of them: the application chart itself, and a paired registration chart whose ApplicationDefinition advertises the application to the Cozystack API and dashboard.

The lifecycle has two sides:

• Publishing turns a repository into an OCI artifact: cozypkg init scaffolds it, cozypkg validate lints it offline, and cozypkg push bundles the packages/ tree into a single versioned artifact in any OCI registry.
• Connecting registers that artifact on a cluster: cozypkg tap (or the dashboard) creates a Flux OCIRepository and materializes the repository’s PackageSource resources. cozypkg add then installs individual applications from the connected repository, and they show up in the catalog.

Key objects

A connected repository keeps its own declared PackageSource name. If that name would collide with a core component or with another connected repository, the connect is rejected instead of overwriting it, so an external repository cannot take over an official PackageSource. Only the name is compared: the ApplicationDefinition resources a repository registers are not checked against the core catalog.

Trust model

Installing an application from a connected repository runs its charts in your management cluster, so connect only sources you trust. (Tapping itself installs nothing; it registers the source.)

Connecting is a standing subscription rather than a one-time fetch. Both connect paths create an OCIRepository pinned to a tag, with interval: 5m, so Flux re-resolves that tag every five minutes and a new revision behind it is pulled and its PackageSource resources re-applied. What the new revision drops is removed as well: a package the publisher stops shipping disappears from every connected cluster, and an installed Package left behind goes Ready=False with PackageSourceNotFound. Whoever controls the tag controls what your cluster reads from then on: re-pushing the same tag reaches every connected cluster within the interval. cozypkg tap rejects digest references, so pinning an immutable digest at connect time is not an option.

Signature verification happens at publication time, not at connect time. cozypkg tap validates an artifact’s structure before it creates anything; the dashboard connect does not, it records the source, and the pull, the digest check and the materialization of the PackageSource resources all happen in the cluster afterwards, so a broken chart surfaces later as a failed install. Neither verifies a cosign signature, and neither sets spec.verify on the OCIRepository. The verification point is the community index CI gate, which pins each release to the entry’s recorded cosign identity; it attests the artifact as of the moment the entry merged, not whatever the tag resolves to later.

Setting spec.verify on the OCIRepository in cozy-system by hand is what closes that gap: Flux then checks the signature on every pull, including the ones the interval triggers. Connecting the same repository again from the dashboard replaces the source’s whole spec and drops the field, so re-add it after a reconnect. See Publishing a Repository for the publication side.

Where to go next

• Publishing a Repository: scaffold, validate, push, and list a repository in the community index.
• Connecting a Repository: discover, connect, install, and disconnect repositories on a cluster.
• cozypkg Reference: every command and flag.