Versions

Overview

Every community package is distributed via a CloudronVersions.json file. This file is a version catalog. Each entry embeds a full CloudronManifest.json for that release, plus publish metadata.

Host the file at a publicly accessible HTTPS URL. Users add that URL in the dashboard or install with cloudron install --versions-url <url>. Updates are picked up automatically when new versions are published.

For the packaging workflow (init, add, revoke, distribute), see Publishing.

Here is an example versions file:

{
  "stable": true,
  "versions": {
    "1.0.0": {
      "manifest": {
        "id": "com.example.test",
        "title": "Example App",
        "description": "This is an example app",
        "tagline": "A great beginning",
        "version": "1.0.0",
        "minBoxVersion": "10.0.0",
        "healthCheckPath": "/",
        "httpPort": 8000,
        "addons": {
          "localstorage": {}
        },
        "manifestVersion": 2,
        "website": "https://www.example.com",
        "packageUrl": "https://git.example.com/example-app",
        "packagerName": "Example Packager",
        "packagerUrl": "https://example.com",
        "iconUrl": "https://example.com/icon.png",
        "tags": [ "test", "collaboration" ],
        "mediaLinks": [ "https://example.com/screenshot.png" ],
        "changelog": "* Initial release",
        "dockerImage": "example/com.example.test:1.0.0"
      },
      "creationDate": "Fri, 20 Feb 2026 20:17:42 GMT",
      "ts": "Fri, 20 Feb 2026 20:17:42 GMT",
      "publishState": "published"
    }
  }
}

Prefer creating and updating this file with the CLI:

cloudron versions init
cloudron versions add
cloudron versions list
cloudron versions verify

Fields

stable

Type: boolean

Required: yes

The stable flag marks whether the catalog as a whole is considered stable.

When stable is false, every version is treated as unstable in the dashboard (install and update dialogs show a warning). When stable is true, only versions whose publishState is not published are treated as unstable.

Example:

  "stable": true

versions

Type: object

Required: yes

The versions object maps version strings to version entries. Keys must be valid package semver (same format as version in the manifest). Each key must match manifest.version inside that entry.

Example:

  "versions": {
    "1.0.0": { ... },
    "1.0.1": { ... }
  }

Revoked versions stay in the object but are ignored when resolving latest or computing updates.

Version entry fields

Each value under versions has the following fields.

manifest

Type: object

Required: yes

The manifest field is a complete CloudronManifest.json for that version. File references such as file://DESCRIPTION.md are resolved when the entry is created with cloudron versions add; the published file contains the inline content.

Publishing requires additional fields beyond a local install. The embedded manifest must include:

• id, title, description, tagline, website, tags, changelog
• mediaLinks (non-empty)
• healthCheckPath
• iconUrl
• packagerName, packagerUrl
• dockerImage (set by cloudron versions add from the last cloudron build)

See the Manifest reference for field details. Use cloudron versions init to add missing publish fields to CloudronManifest.json.

creationDate

Type: date string

Required: yes

The creationDate is when the version entry was first added. The CLI stores this as a UTC date string (for example, the result of (new Date()).toUTCString()).

Example:

  "creationDate": "Fri, 20 Feb 2026 20:17:42 GMT"

ts

Type: date string

Required: yes

The ts field is the last modification time of the version entry. It is set when the version is added and updated by cloudron versions update.

Example:

  "ts": "Fri, 20 Feb 2026 20:17:42 GMT"

publishState

Type: string

Required: yes

The publishState controls whether users receive the version:

Value	Meaning
published	Available for install and updates (when the catalog stable flag is true)
testing	Installable, but marked unstable in the dashboard
revoked	Hidden from latest and update checks. Already-installed apps keep the version

Set the state when adding or updating:

cloudron versions add --state testing
cloudron versions update --version 1.0.0 --state published
cloudron versions revoke

Only a version currently marked published can be revoked.

URL resolution

The versions URL must use HTTPS. Browser links from common git hosts are accepted; the platform resolves them to a raw JSON URL when possible:

• GitHub blob URLs → raw.githubusercontent.com
• GitLab /-/blob/ URLs → /-/raw/
• Gitea / Forgejo / Codeberg /src/ URLs → /raw/

A directory URL that does not end in CloudronVersions.json has that filename appended. Static hosts that already serve the file directly work as-is.

Optionally pin a version by appending @<version> (for example, https://example.com/CloudronVersions.json@1.0.0). Without a suffix, latest is used (highest non-revoked semver).