The contract a plugin is written against: the fields of plugin.yaml, the
two gRPC services the backend and the server exchange, and the window.evey
bridge an interface module gets in its frame. The walkthrough that uses them
is Writing a plugin; what each permission allows and what the
installer refuses is in Permissions and slots.
Every ZIP carries a plugin.yaml (or plugin.yml) at its root, 1 MB at
most.
name: my-plugin # required; unique, kebab-case
version: 1.2.3 # required; semver, X.Y.Z or X.Y.Z-label
kind: plugin # required; "plugin" or "theme"
language: nodejs # required for a plugin; a runtime of the image
entrypoint: node index.js # required for a plugin; the command line the server runs
display_name: My Plugin # optional; a string, or a map {en: ..., fr: ...}
description: "..." # optional
author: "..." # optional
min_evey_version: "1.0.0" # optional; install/update refused when above the server version
permissions: # what the backend and the interface may call
- network
- media.read
external_fetch: # required with "network"; bare hostnames only
- api.themoviedb.org
capabilities: # the roles the plugin says it fulfils
- metadata.provider
web_root: public/ # required when frontend is declared; served as static assets
frontend:
- slot: home.section # one of the allowed slots
src: public/front.js # must be under web_root
config_schema: # the fields of the Config panel on the plugin's card
api_key:
type: password # never sent back to any client
label: API key # not rendered: the panel labels fields by key
required: true
city:
type: string
default: Paris
description: Resolved through geocoding| Field | Rule |
|---|---|
name, version, kind |
Required. version must match X.Y.Z or X.Y.Z-label; an update must carry a higher version than the installed one. |
display_name |
The name people see; name stays the identifier an update is matched on. One string counts as English and stands for every language; a map is keyed by language tag (en, fr, pt-BR). Each value is 1 to 40 characters, without surrounding spaces or control characters. Today the theme picker shows it. |
language |
Required for kind: plugin: python, nodejs, php, ruby, lua, bash, sh or go. It picks the runtime check and the stubs copied next to the entrypoint; it does not launch anything. |
entrypoint |
Required for kind: plugin. The first token is the interpreter (or the binary, with native-binary), the rest its arguments; the process runs in the plugin's directory. |
permissions |
Each value must be in the permissions catalog. network requires a non-empty external_fetch. |
external_fetch |
Hostnames. A scheme and a trailing path are dropped at parse; hosts match exactly, a *.example.com wildcard is refused at install; an entry without a port allows ports 80 and 443 only, host:port allows that port only; an IP literal refuses the install (rules). |
capabilities |
metadata.provider, media.read, media.write, webhook.receiver or notification.sender; anything else is refused. A theme may declare none. |
web_root |
Required when frontend is non-empty; relative, no .., no backslash. . serves the whole plugin directory and only logs a warning. |
frontend[] |
slot must be in the slot list; src must be under web_root. |
config_schema |
A map of field name to {type, label, description, required, default, min, max, options}; label is not rendered, the panel labels fields by key. Types: string, text, password, boolean, integer, number, select (with options: [{value, label}]). |
A theme (kind: theme) must not declare language, entrypoint,
permissions or capabilities; its format is in Themes.
Secrets. A field of type: password, or with secret: true, is stored
and handed to the backend as usual but comes back masked from every read
route, the admin Config panel included. Saving the panel with the mask
unchanged keeps the stored value, so editing another field never wipes a
secret.
The backend process and the server speak gRPC over two Unix sockets whose paths arrive in the environment:
EVEY_PLUGIN_ID=<plugin id>
EVEY_PLUGIN_SOCK=<path> # your process listens here and serves PluginService
EVEY_HOST_SOCK=<path> # your process dials here to call HostService
The server authenticates the process on its socket by the PID the kernel
reports (SO_PEERCRED); no token is handed to the process. Calls are limited
to 600 per minute per plugin. proto/plugin/v1/plugin_api.proto is the
contract; stubs for the bundled languages are copied next to the entrypoint
when the plugin starts (prerequisites).
| Method | When |
|---|---|
Initialize(plugin_id, config, host_version) |
Once the process has bound its socket. config carries the values of config_schema the administrator set. Answer success: false with an error to refuse to start. |
HealthCheck() |
Periodically, to tell a live process from a hung one. Answer healthy: true while you can serve. |
Shutdown(reason) |
When the plugin is disabled, updated, uninstalled or the server stops. Exit soon after answering. |
OnEvent(event_type, payload, source) |
Only metadata.request, to a plugin with the metadata.provider capability (metadata requests below). Any other plugin receives no event: answer handled: false. |
GetCapabilities() |
Defined in the contract; the server does not call it today. |
A call whose permission the manifest does not declare is refused with
PermissionDenied. Methods marked not served answer Unimplemented; they
are part of the contract for a later version and are listed so that a stub
does not mislead you.
| Method | Permission | Notes |
|---|---|---|
Log(level, message, fields) |
none | Written to the plugin's log, shown under Logs on its card. |
GetConfig(key) / SetConfig(key, value) |
none | The plugin's configuration: the values from the Config panel, plus keys the plugin writes itself. At most 256 keys, keys of 256 bytes, values of 16 KiB. |
GetData, SetData, DeleteData, ListDataKeys |
none | The data store below. |
EmitEvent(event_type, payload) |
none | Published on the server's event bus as plugin.event.<event_type>, where webhooks can subscribe to it. |
GetMediaItem(id), ListMediaItems(library_id, type, parent_id, limit, offset) |
api.library or media.read |
The full media record, including file_path, provider_ids and genres. |
Fetch(url, method, headers) |
network |
The only way out of the sandbox: http or https, GET or HEAD, a host of external_fetch, private addresses refused after resolution and through redirects. The body is capped at 8 MiB (truncated says so) and the whole request at 20 seconds. The server attaches no credential of its own. |
SearchMedia, GetMediaStreams, GetChapters, GetSubtitles |
api.library or media.read |
Not served. |
UpdateMetadata(media_item_id, fields, provider_ids) |
api.metadata or media.write, and the metadata.provider capability |
Gives your text for one movie or series unasked, as a metadata answer would. fields carries locale (required) and any of title, overview, tagline; the text replaces what you gave for that locale, and fields holding only locale removes it. provider_ids is refused: TMDB identifies the item. What one plugin stores is bounded: 16 locales per item, 200 000 texts and 128 MiB in all. Past a bound the call answers RESOURCE_EXHAUSTED; replacing or removing a text you already gave stays possible. |
GetUserPreferences |
api.user |
Not served. |
SendNotification |
notification.sender |
Not served. |
Each time the server matches or refreshes a movie or a series from TMDB, it
sends every enabled metadata.provider plugin an OnEvent with
event_type metadata.request, one plugin after the other, and waits up to
15 seconds for each. The payload:
| Field | Content |
|---|---|
media_item_id |
The item's id, for a later UpdateMetadata. |
type |
movie or series. |
title, original_title |
TMDB's title in the server's language, and the original one. |
year |
Absent when unknown. |
provider_ids |
tmdb, imdb and the other ids known for the item. |
language |
The language of TMDB's text, for example fr. |
locales |
Every language the server shows. |
Answer handled: true with a result of:
{
"locale": "fr",
"title": "...",
"overview": "...",
"tagline": "...",
"translations": {
"de": { "overview": "..." }
}
}The top-level fields are in locale, or in the request's language when
locale is absent; translations adds other languages. Leave out a field you
do not cover. Language tags are cut to their language (fr-FR reads fr),
and a field over 8 KiB is ignored. An answer replaces everything you gave for
the item before; handled: false, or an answer with no text, says you do not
know the item and clears what you gave for it. An error or a timeout keeps what you gave.
The administrator chooses which of title, overview and tagline your text
replaces, and can ask you about the whole library at once
(Metadata plugins). Seasons and episodes are
not sent.
Every plugin owns a persistent key/value store, with no permission to declare: cursors, caches, a last-sync timestamp, anything to remember across restarts. Values are opaque strings; encode JSON yourself. The plugin id comes from the authenticated socket, so a plugin reads and writes its own namespace only, and the whole store is deleted with the plugin.
| Method | Purpose |
|---|---|
SetData(key, value) |
Create or replace a value. |
GetData(key) |
Returns value and found. |
DeleteData(key) |
Remove a key. |
ListDataKeys() |
The plugin's keys. |
This store is global to the plugin. Data per user (a preference of the
person looking at the widget) lives on the interface side, through the
prefs permission below.
An interface module runs in a frame with an opaque origin, under a policy of
default-src 'none': no access to the host page, its cookies or its storage,
no form, no popup, and a connect-src limited to the hosts of
external_fetch over https. Everything else goes through window.evey,
injected before the module runs. The same module runs unchanged in the web
app and in the mobile and television apps.
Called once with the context the host sends; a callback registered after the context arrived is called immediately.
evey.onInit(function (data) {
// data.config - the plugin's config values (config_schema)
// data.context - the host context
// data.locale - the active locale, e.g. "en-US"
// data.theme - "dark" or "light"
// data.surface - "web", "mobile" or "tv"
// data.suggestedHeight - home.section only: the height (px) the host recommends
// data.viewportHeight - tv only: the panel height in dp
});Moves the host application to path. Only /home, /library, /media,
/player, /settings and /search prefixes are followed; anything else
(the admin area, sign-in, an absolute URL) is dropped silently.
Shows a toast in the host interface. level is "success", "error" or
"info"; message is plain text, cut at 200 characters; at most 3 toasts
per second are shown.
Asks for the slot to be height pixels tall, clamped between 50 and 800.
0 collapses the slot: a widget with nothing to show takes no room. A
home.section widget opens at data.suggestedHeight without doing anything:
the host knows the surface it put you on and recommends the height a home
widget has there, so every widget lands the same size. Resize only when you
know better.
The current user's preferences in the plugin's own namespace, bound to (this plugin, this user) by the token the host holds for the frame. Each call returns a promise; a missing permission rejects it.
await evey.prefs.set("units", "celsius");
const { value, found } = await evey.prefs.get("units");
const all = await evey.prefs.list(); // [{ key, value }]
await evey.prefs.delete("units");A safe projection of media items: id, title, type, year, overview, poster URL. Never a file path, a size, a provider id or a stream.
const item = await evey.media.get(id);
const page = await evey.media.list({ libraryId });
const data = await evey.media.poster(id); // the poster as a data: URLposter returns a data: URL because the frame's policy forbids loading an
image from the server directly; use it as an <img> source or a texture.
Reads one of the plugin's own web_root files, by relative path, as a
data: URL: a file the backend wrote at run time becomes usable in the frame
without a cross-origin concern. Only the plugin's own assets are reachable.
The television app runs the module in a WebView, and a few things that are true in a browser stop being true there:
- Do not size from your own viewport. Inside the WebView,
window.innerHeightis the slot the host just granted you. Size fromdata.viewportHeightordata.suggestedHeight. - No focus, no pointer. The widget never receives the D-pad focus and there is no hover; anything interactive belongs to the web and mobile surfaces.
- Keep text away from the edges. Televisions overscan: leave about 5% of the width and height free on every side.
- Test WebGL on a real box. A shader runs on the box's GPU and driver,
not on your desktop's; keep noise coordinates bounded.
tests/plugins/weather-v2is the reference widget for all of the above.
| Slot | Where it appears |
|---|---|
home.section |
A content section on the home page |
home.hero |
The hero banner area of the home page |
library.sidebar |
A sidebar panel in library views |
media.detail.sidebar |
A sidebar panel on a media detail page |
player.overlay |
An overlay layer on the video player |
settings.user.appearance |
The appearance section of the user settings |
sidebar.bottom |
The bottom of the main navigation sidebar |
admin.nav |
One entry in the admin menu, opening the plugin's own page |
admin.nav is the only admin-area slot. It injects nothing into existing
admin screens: it adds a menu entry that opens the plugin's page in the same
sandboxed frame, on an admin-gated route. Asking for it shows in the consent
diff. Every other admin.*, login.*, setup.* and profile.security.*
slot is refused at install.
A capability declares the role the plugin says it fulfils:
metadata.provider, media.read, media.write, webhook.receiver or
notification.sender. The installer checks the name, the administrator sees
the list in the preview and any addition at update, and the Security
Dashboard records it. The server routes on one of them: a
metadata.provider receives the metadata requests and
may call UpdateMetadata. The others route nothing today; a
webhook.receiver receives no inbound request. What a plugin can actually
do is decided by its permissions.
public and prefs are declared under permissions like the others. They
grant nothing to the backend process; they unlock evey.media.* and
evey.prefs.* in the frame. The frame never holds a token: the host mints a
five-minute token scoped to (plugin, user) and proxies the calls, and the
server refuses by default every method the token's scopes do not name
(ADR-0012).
!!! note "What a plugin can never ask for"
admin.*, auth.*, system.*, user.write and library.write are
hard-locked: a manifest that names them is refused, a token can never
carry them, and admin methods refuse a plugin token whatever its scopes.
examples/plugins/ holds working plugins in the current manifest format:
starters in Node.js and Python (nodejs-example, python-example), a
metadata provider (metadata-example), a webhook receiver
(webhook-receiver), a home widget with a build step (weather), the data
store with the public and prefs permissions and the admin.nav slot
(data-demo), a tour of every config_schema field type, with an admin.nav page
(config-demo),
and two themes (theme-dark-blue, open-workshop). make plugin-zips
packages them all.