Overview
What is an app
Apps are named, versioned packages of installed files that declare optional contributions — an iframe UI surface is just one of them.
An app (kind: Application) is a named, versioned package of installed files that declares
optional contributions to a workspace. The most visible contribution is a UI surface: a web
experience Verentis renders inside a workspace in a sandboxed <iframe>. It can be resolved by the MIME
type of a file the user opens or explicitly exposed as a file-independent workspace surface with
spec.launch. An app can also — or instead — install a collection of files into the workspace,
where their behaviour emerges from each file's type. The iframe is optional.
The reference iframe apps that ship with Verentis are an Image Viewer (image/*) and a Smart
Editor (Monaco-based, for text/*, application/json, application/yaml, …). A headless app,
by contrast, ships no iframe at all — for example a collection of Python scripts and a daily schedule
that run on the Python execution engine.
Anatomy of an app
A manifest (*.app.yaml)Declares identity, the permissions/scopes you need, and the app's contributions: optionally an iframe
UI surface (entry + MIME claims + sandbox), an install map
of files to place in the workspace, and/or an OAuth client. Installing it adds the app to a workspace.
A UI surface served over HTTPS (optional)Any front-end stack. The spec.entry URL is what Verentis loads in the iframe. In development this is
your dev server; when published it's your hosted app. Omit it entirely for a headless app.
Installed files (optional)Via the install map an app places dashboards, scripts, schedules, triggers or seed data into
workspace paths. Each file is seed (install once, user-owned) or managed (app-owned, replaced on
upgrade, removed on uninstall). Behaviour emerges from each file's type.
The SDK bridge (for iframe apps)@verentis/sdk connects your iframe to the host over postMessage, giving you a discriminated file
or workspace launch context plus scoped API access — without handling raw credentials.
How a headless app runs
Install places the files
The install map scatters the app's files across the workspace — e.g. scripts to /scripts/, a
*.schedule.yaml to /automation/, seed data to /data/ — and anchors the app record under
install-root.
Behaviour emerges from each file's type
A placed *.schedule.yaml registers as an ExecutionSchedule and runs on its cron; a *.trigger.yaml
runs on file events; a seeded vendor-MIME JSON resolves to the app that claims it; a .py a user opens
runs on the Python engine.
Upgrade & uninstall respect the lifecycle
Re-installing replaces managed files and removes ones no longer shipped; uninstall removes managed
files and the app record. seed data (and user edits to it) is always preserved.
How an iframe app runs
A user opens a file or launches an app
For a file, Verentis picks the highest-priority app that claims its MIME type. A spec.launch app can
also open directly from Home or a personal pin without a selected file.
Your page loads in a sandboxed iframe
The host renders spec.entry with the sandbox flags from your manifest. Your app initialises the SDK.
The SDK bridges to the platform
Through the bridge your app gets surface: 'file' with file metadata or surface: 'workspace'
without a file. SDK calls use a host-injected token governed by the permissions the workspace consented
to.
Modes: view vs. edit
Each MIME type you claim declares a mode — view or edit. A viewer claims view; an editor claims
edit and requests write permissions (node.node.create, node.node.update). The mode helps the
workspace decide which app to offer for an "open" vs. an "edit" intent.