Overview and capabilities

Overview

A Baram plugin is a directory containing a manifest (baram-plugin.json) and a single ESM bundle (typically dist/index.mjs). The bundle exports an activate(context) function (and optionally deactivate()); the host calls activate with a capability-gated ExtensionContext object that is the plugin’s only way to touch the app.

Every plugin declares one of two tiers in its manifest, and the tier decides what “capability” means:

• "trust": "sandboxed" — the default, and what you should write. The plugin runs in its own isolated webview with no access to the app’s JavaScript, and every privileged operation goes through a Rust broker that authorizes the call against the plugin’s granted capabilities. Here the capability list is a real boundary.
• "trust": "trusted" — the same JavaScript context as the editor, Obsidian’s model. Necessary for tiptapExtensions, which need direct access to the live editor to register a ProseMirror plugin on it — not the schema; a "plugin" contribution cannot touch the schema at all, which is exactly why node/mark contributions aren’t supported (see Tiptap Extension plugins). Here the capability system is only an API gate: the plugin can reach around it, so the list describes intent rather than limiting anything. Installing one requires an explicit acknowledgement of exactly that.

Write sandboxed unless you are contributing a Tiptap extension or DOM-mounted UI. See Trust model & security before installing or authoring anything sensitive.

Capabilities

Plugins must declare every capability they need in the manifest. Users approve these at install time (registry installs) and, on a release build, before a dev folder’s code first runs; a development build loads a dev folder without asking (see Trust model & security). Accessing an API whose capability was not declared throws a clear error (“Plugin requires "X" capability to access …”) instead of silently no-oping — the context hands back a denied proxy for any ungranted API.

Capability	Description	Sensitivity
commands	Register and execute editor commands
editor	Read and modify document content
editor:readonly	Read document content (no modification)
events	Listen to editor events
extensions	Contribute a ProseMirror plugin to the editor (trusted tier only)
files	Read and write files in the vault; also ctx.index and vault:changed	sensitive
files:readonly	Read files in the vault (no writing); also ctx.index and vault:changed
sidebar	Add panels to the sidebar — a trusted plugin mounts its own DOM, a sandboxed one declares panels
statusbar	Display items in the status bar
settings	Declare options in the settings screen
ai	Access AI/LLM features	sensitive
network	Make network requests	sensitive
storage	Use a plugin-private key/value store	sensitive
viewer	Register custom file-type viewers
codeblocks	Draw code blocks of the languages it declares — see Code block renderers

ai and network are the highest-sensitivity capabilities — see Trust model & security for exactly what they allow. files and storage are also flagged because they touch data outside the plugin’s own memory (vault files / a persistent on-disk store), even though they’re vault- or plugin-scoped rather than globally unrestricted.