Oruva
Plugin API v1 · Get Started
Plugin API v1 · manifest schema 2

Build for Oruva

Add tools to Oruva's right-click menu with a local-first, out-of-process plugin model and an explicit trust boundary.

Create your first pluginManifest reference

Plugin API v1 · manifest schema 2 · Shipped platform behavior as of 2026-09-07. This is the complete guide for oruva.app/developers/plugins. Two version numbers appear throughout and they are deliberately different: the API is v1 (the execution contract, the bridge messages, the placeholder set, the local HTTP endpoints) and the manifest schema is 2 (the shape of plugin.json, which added the required capabilities block). The machine-readable contract is plugin_sdk/schema/plugin.schema.json inside the SDK.

An Oruva plugin adds actions to the assets in an Oruva library. When a user right-clicks an asset, your plugin's actions appear in the Plugins submenu; choosing one either runs your program directly or opens your action's optional interface.

Three principles shape the whole platform:

Local-first. A plugin is a folder on the user's disk. No account or website is required to run a locally installed plugin. Plugins may still use the network when they declare exactly where and why; the Plugin Center is a manager and catalog, not a runtime dependency.
Out-of-process. Your Python script or executable runs as a separate process. An optional HTML interface runs separately in a script-only sandboxed iframe and talks to Oruva through a small message bridge.
Explicit trust. Every plugin declares permissions and structured capabilities in its manifest. The user sees them and must approve the plugin before it can run — and approval is bound to the entry, runtime, permissions, capabilities, action definitions (including args and ui), and the hash of every file in the folder. Any change to any of those invalidates the approval automatically.

Versioning promise

Plugin API v1 fields will not silently change meaning. New abilities such as actions[].ui and actions[].icon appear as optional fields; the structured capabilities object carries its own required version so that the capability contract can evolve without touching the manifest schema. Anything incompatible requires a new schema_version (as schema 2 did when it made capabilities required) or a new capability version. Version your own plugin semantically — the update badge users see is driven by your version field.

Explore the documentation

Start with the quick start, then keep the reference pages open while you build.

Get StartedCreate your first pluginCreate, link, validate, and debug a plugin project.Get StartedPlugin anatomyThe files in a plugin folder and the path rules they follow.Plugin TypesHeadless actionsThe process, argument, output, and timeout contract for headless actions.Plugin TypesUI actionsModal UI actions, the sandboxed bridge, streaming events, and multi-selection.ReferenceManifestPlugin API v1 manifest fields, actions, and argument placeholders.ReferencePermissions & trust modelPermission declarations, approval invalidation, and the Plugin API v1 trust boundary.ReferencePost-run reconciliationConnect UI-action file writes to Oruva's library refresh pipeline.ReferenceIconsSupported plugin icon formats, limits, placement, and presentation.DistributionPackaging (.oruvaplugin)Build deterministic, integrity-checkable Oruva plugin packages.DistributionPlugin Center & catalogDiscover with real icons and one-button installs, updates that swap atomically, and plain-language management.ResourcesCase study: 3DSky Hi-Res MatchA shipped search-and-act UI plugin using the Oruva bridge.ResourcesTroubleshootingSymptoms and causes across manifests, approval, UI runs, previews, and packages.