This page is for the administrator: how to install a plugin or a theme, what you accept when you do, and what the server lets it touch on your host. Everything happens in Admin → Plugins; the pages for plugin authors are listed at the end.
A plugin adds to Evey what it does not do by itself: a section on the home page, an overlay in the player, a metadata source, a theme. Each plugin is a separate process that talks to the server through a local socket, confined by a sandbox and limited to the permissions its manifest declares. Its interface, when it has one, runs in an isolated frame of the page.
- In Admin → Plugins, open Install Plugin and choose the Plugin
file (.zip). If the author ships a signature, add it in Signature file
(.zip.sig, optional). The From URL tab installs from an
https://link instead; a plainhttp://link or a path on the server is refused (see Where the package comes from). Append#sha256:<hash>to the link to have the download checked. A repository link,https://github.com/<owner>/<repo>, installs the zip of its latest release, checked against the sha256 the release publishes, and the plugin then follows that repository for its updates (see Automatic updates). - Preview & Install analyses the package without installing it. The preview shows the Permissions and Capabilities the plugin asks for, the result of the Static Analysis and, when a signature was given, the Signature verdict with the publisher. The slots and the hosts are shown at update and on the Security Dashboard.
- Read that list as the contract: those are the only things the plugin will be able to do. Confirm, and the plugin starts.
A package whose analysis finds a critical pattern is refused, whatever you
answer. Warnings are shown and left to you. The plugin's language must be
among the Available Runtimes of the server: the default image ships
Python, Node.js, PHP, Ruby and Lua; the -nodejs image keeps Python and
Node.js and the -lean image keeps Python only.
!!! tip "Signed plugins"
A plugin author can sign the ZIP with cosign;
the author's public key travels inside the package. Evey checks the
signature on its own (no cosign binary) and tells you Signed by
when the key is in your Trusted publishers list,
Signed, unknown key with its fingerprint otherwise (one click trusts
it), Unsigned or Invalid. An update that changes key, or drops the
signature, waits for your explicit acceptance. The policy decides the
rest:
```sh
EVEY_PLUGINS_COSIGN_POLICY=enforce # off | warn | enforce (default)
```
With `enforce`, only trusted publishers install: the Evey project's key is
trusted from the start, and another publisher's key can be trusted from
the install preview. With `warn`, the verdict is shown and nothing is
blocked. Authors: see
[Sign your plugin](plugins/dev-setup.md#7-sign-your-plugin).
On the plugin's card, Update from source… takes the https:// link of the
new ZIP and shows the same preview. An update must carry a higher version than
the installed one. When it asks for new permissions, capabilities, slots or
hosts, the preview says This update requests new permissions and lists the
difference: nothing is applied until you choose Approve and install. The
package analysed is the package installed: its hash is checked again when the
update is applied. The source can also be the plugin's repository link: the
preview is then of its latest release.
A plugin installed from its repository link, or from one of that repository's release links, follows the repository. The Updates section of its card shows the repository (Change sets another one, or none), the Automatic updates switch, on by default, and what the last look found. Evey looks at the latest release a few minutes after it starts, then every hour; Check now looks at once.
A newer release is judged before anything runs:
| What the release holds | What happens |
|---|---|
| Nothing new: no new permission, capability, slot or host, no new kind of analysis warning, the same signing key | Installed on its own: Version … installed automatically. |
| Something new (a permission, a host, a change between theme and plugin, another language), a pre-release, an installed version that is not signed, or the switch off | Version … awaits your approval, and the admins get a notification. Review opens the usual update preview, where you approve the difference. |
| Code the static analysis refuses | Version … refused, with the reason, and the admins get a notification. It is not installed, automatically or by hand. |
An unsigned plugin never updates on its own: whoever took over its repository could publish code the analysis does not catch, and only a signing key they do not hold stops them. A notification is sent once per release, not every hour. The check reads the GitHub API and downloads from the repository's release files, and from nowhere else.
The repository is followed by the permanent number GitHub gives it, not by its name: a renamed or transferred repository is still followed, and whoever registers an abandoned name gets nothing followed. Installing from the repository link installs the release the preview showed, even if a newer one is published in between. A release already judged is not downloaded again until something changes on either side. Evey asks GitHub without a token, which allows 60 requests an hour per address: one per followed plugin and per hour; when the quota is spent, the check stops until its next run.
Each card shows the plugin's state (Enabled or Disabled) and offers:
| Action | What it does |
|---|---|
| Enabled / Disabled | Starts or stops the plugin's process. A disabled plugin keeps its files and its configuration. |
| Config | The settings the plugin declares (an API key, a city, a unit...). Secret fields are shown masked and are never sent back to the browser. |
| Logs | The last lines the plugin wrote through the host. |
| Metadata | On a metadata plugin only: the fields it replaces and the fetch of the existing library (below). |
| Uninstall | Removes the process, the files and the plugin's stored data. |
Resource limits, at the top of the page, caps every plugin process. The values in the panel are the defaults; the environment variable sets them when the panel has never been saved.
| Field | Default | Environment variable |
|---|---|---|
| Max memory (MiB) | 256 | EVEY_PLUGINS_MEMORY_MB |
| Max processes | 64 | EVEY_PLUGINS_PIDS_MAX |
| Max disk (MiB) | 100 | EVEY_PLUGINS_DISK_MAX_MB |
| CPU nice (0-19) | 10 | EVEY_PLUGINS_CPU_NICE |
| Sandbox mode | auto |
EVEY_PLUGINS_SANDBOX_MODE |
Memory, processes and disk apply at the next sweep of the monitor, which stops
a plugin that exceeds them; the CPU priority applies to plugins started
afterwards, and a sandbox-mode change restarts the running plugins at once. 0 restores the default for memory and processes; only the disk limit treats
0 as off.
The Security Dashboard keeps, per plugin, the findings of the analysis, the
signature result and the last error. Its Host sandbox line shows the
sandbox mode actually in force on this machine: if it reads basic, the host
offers no per-path filesystem isolation, and
Plugin sandbox setup explains what to change.
Plugins are enabled by default. EVEY_PLUGINS_ENABLED=false turns the whole
subsystem off.
A metadata plugin (capability metadata.provider) gives its own text for your
movies and series, from a source other than TMDB. It does not replace TMDB:
TMDB still identifies each title and gives its cast, its artwork, its ratings,
its collections and its translations. The plugin's text is kept beside TMDB's,
and shown in its place field by field.
What a viewer reads, from the weakest to the strongest:
- TMDB's text, in the viewer's language when TMDB has it;
- the plugin's text in that language, for the fields the plugin is allowed to replace;
- your own edit of the title (Edit metadata on its page), which always wins.
Metadata on the plugin's card chooses the fields it replaces among Title, Overview and Tagline. Until you choose, a plugin replaces the overview and the tagline, never the title. A change applies at once to what the plugin already gave; nothing is fetched again.
The plugin is asked about every movie and series as it is matched or refreshed. Fetch for the whole library, on the same panel, asks it about the titles already there, one after the other, and shows how far it has gone and, at the end, how many it found and how many got no answer. A refresh of the title from TMDB never overwrites the plugin's text; disabling the plugin hides that text, uninstalling it deletes it.
Seasons and episodes keep TMDB's text, and search still matches TMDB's titles.
Whatever its manifest says, a plugin:
- sees its own directory, not the server's data nor the media files;
- has no direct network access: a plugin with the
networkpermission reaches only the hosts it declared, through the server, withGETandHEAD; - cannot start child processes unless it declares
subprocess; - runs under the resource limits above and, when the host allows it, under a separate user.
Its interface is confined to the slots the manifest declares: a section or the
hero area of the home page, a sidebar panel in a library or on a detail page,
an overlay of the player, the appearance settings, the bottom of the
navigation sidebar, or one entry in the admin menu that opens the plugin's own
page. A plugin can never draw into the sign-in, setup, security or existing
admin screens. In its frame, it has no access to the page, your cookies or
your session: what it reads from the server goes through a short-lived token
limited to the two permissions it may ask for (public for a safe projection
of media titles and posters, prefs for the current user's preferences in its
own namespace).
The permissions a plugin can ask for are listed in Permissions and slots. How the sandbox works, and what it still cannot prevent, is in Plugin sandbox and threat model.
!!! warning "The server checks where a plugin talks, not what it says" Once a host is on a plugin's list, the server cannot inspect what the plugin sends to it. Review a third-party plugin before installing it, as you would any software, and treat its host list as the list of parties that may receive your library's titles.
A theme is a package of kind: theme with no process: a stylesheet, and
optionally a script confined to a hidden frame. It is installed from the same
Install Plugin dialog; the stylesheet is sanitized at install. Each user
then picks it under Settings → Appearance → Theme. What a theme may
contain is described in Themes.
| Page | Contents |
|---|---|
| Writing a plugin | A first plugin step by step, the install loop, signing, distribution. Start here. |
| Plugin API reference | The manifest, the backend calls and data store, the evey.* bridge of the interface. |
| Permissions and slots | What a manifest may declare, what is checked at install, the external fetch rules, the slots. |
| Themes | Restyling the interface with CSS and a sandboxed script. |
| Webhooks and API keys | Integrating Evey with other tools without writing a plugin. |