Publish an application

This is the end-to-end recipe for shipping an application to the marketplace: from a working, locally-registered app to a signed, moderated, installable listing. It assumes you have already built the app and understand the app manifest — here we focus on packaging and publishing.

1. Install the CLI and sign in

npm install -g @verentis/cli

# The CLI targets production by default. Authenticate with a browser device sign-in (just `verentis login`),
# or non-interactively with an identity token from the web app (exchanged per request for short-lived, scoped
# access tokens) or a vrt_ API key.
verentis login --token <identity-token>

verentis whoami            # confirms your identity / publisher, if any

2. Become a publisher (once)

Your publisher is your developer identity; its name prefixes every package you ship (acme/my-app). Create it once:

verentis publisher create \
  --name acme \
  --display-name "Acme Inc." \
  --website https://acme.example \
  --email dev@acme.example

3. Generate a signing key (once)

verentis keygen              # Ed25519 keypair; registers the PUBLIC half with your publisher

The private key stays at ~/.verentis/keys/default.json and never leaves your machine. From now on verentis pack signs every build automatically. A publisher with registered keys must sign its uploads.

4. Write the manifest

Scaffold a manifest next to your app, or reuse the *.app.yaml you already develop with:

verentis init --kind application --name my-app

Fill in the app spec and — crucially for packaging — the packaging section:

api-version: verentis.io/v1
kind: Application

metadata:
  name: my-app
  display-name: My App
  description: What it does, in one line
  icon: layout-dashboard
  version: 0.1.0
  author: Acme Inc.

spec:
  entry: https://app.acme.example        # hosted app origin (HTTPS, stable)
  scope: global

  # What files your app opens, and how it is discovered
  mime-types:
    - pattern: application/json
      mode: edit
      priority: 200

  # Bundled JSON Schemas etc. — referenced manifest-relative so they resolve after install
  entry-points:
    - mime-types:
        - pattern: application/vnd.acme.report+json
          json-schema:
            source: ./schemas/report.schema.json

  permissions:
    - node.file.read          # request the FEWEST scopes you actually use

  sandbox:
    allow-scripts: true
    allow-same-origin: true
    allow-popups: false
    allow-forms: true

  # Only if your app signs users in
  oauth:
    client-type: public
    redirect-uris:
      - https://app.acme.example/auth/callback

packaging:
  publisher: acme                          # your publisher name
  files:                                   # payload globs, relative to this manifest
    - "schemas/**/*.json"
  encryption: none

See the app manifest reference for every field.

5. Pack and verify

verentis pack                       # → my-app-0.1.0.vpkg  (digested + signed)
verentis verify my-app-0.1.0.vpkg   # checks digests and your developer signature

pack computes a SHA-256 digest for manifest.yaml and every bundled file, signs the digest document (DSSE / Ed25519), and produces a single .vpkg tarball. The registry rejects any upload whose contents don't match its digests.

6. Publish

# First publish creates the listing. Default visibility is PRIVATE — pass --visibility Public
# to list it in the public catalog.
verentis publish my-app-0.1.0.vpkg --visibility Public

Every upload lands as Submitted and enters the moderation queue.

7. Moderation → Published

A reviewer inspects your manifest — the requested permissions, capabilities, sandbox and oauth settings are what they judge, so keep them minimal and legible. On approval the marketplace countersigns your package and the version flips to Published and installable. Rejections come back with notes; fix them and publish a new version (versions are immutable — see Versioning).

8. Try the install

From any workspace you belong to:

verentis install acme/my-app --workspace <workspaceId>

…or open the marketplace, find your app, and Install — the package is pulled into the chosen workspace as a manifest node with your bundled files as children. Opening a matching file now launches your app exactly as it did in local development.

Recap

Next