Extension model
The extension model
How Verentis discovers, installs, registers and governs the extensions you build.
Every Verentis package — application, execution engine, or file bundle — follows the same lifecycle. Learn it once and it applies to anything you build.
One envelope, three kinds
All extensions are declared with a Kubernetes-style manifest envelope:
api-version: verentis.io/v1
kind: Application # or ExecutionEngine, or Bundle
metadata:
name: my-extension
version: 1.0.0
spec:
# kind-specific configuration
The kind selects the package type; spec carries kind-specific configuration and may be omitted by a
plain Bundle. See
Manifests: the contract for the shared fields.
Install = a manifest in the VFS
The workspace virtual file system (VFS) is the source of truth for what's installed:
Add a manifest to install
Placing a valid *.app.yaml or *.engine.yaml in the workspace installs the extension. It can live in
a global /applications/ folder for workspace-wide availability, or be co-located with the
content it serves.
Remove a manifest to uninstall
Deleting the manifest uninstalls the extension. By default this is a soft uninstall — the extension's security resources (scopes, grants, OAuth client) are preserved so reinstalling restores its configuration. An optional cleanup removes them.
The marketplace just writes the manifest
Installing from the marketplace does the same thing under the hood: it writes the extension's manifest into your workspace VFS as a content-bearing node, with the package's bundled files as its children.
How registration works
When a manifest appears in the VFS, Verentis registers it centrally and the relevant service projects its own view of it:
manifest in VFS
│
▼
Resource registry ──► one registration per manifest (any kind)
│
├─► Apps ──► App installation (consent, scopes, OAuth client)
└─► Engines ──► Engine projection (file-type resolution, runtime)
You don't call these services directly to install — you just manage the manifest file. Registration, projection and resolution happen for you.
Resolution: matching extensions to files
- Apps are matched to a file by its MIME type (most specific, highest priority wins).
- Engines are matched to a file by its type/extension.
This is why declaring your mime-types (apps) or file-types (engines) accurately matters — it's how
users reach your extension. See File types & the MIME registry.
Governance
Extensions are first-class governed entities. Apps declare the OAuth client and scopes they need; on install, a workspace admin reviews and consents to those permissions before the extension becomes active. Admins can see installed extensions, their requested permissions, and their defined scopes.