Plugins

A plugin adds something to your server that did not ship with it. A metadata source for a collection nothing else identifies properly, extra detail on a film’s page, a service you use that we have not built support for.

Plugins are free. Installing one is the owner’s job: you decide what runs on your server, and nobody else on it can install, remove or update anything.

Two things are each person’s own, though, and those live in every app: whether a plugin is told what they watch, and any setting a plugin marks as personal. Both are covered below.

Installing one

Installing and configuring happens in a browser. Open your server and go to Settings → Plugins.

The card has two lists. Installed is what you already have. Available is the catalog: everything we host, with what each one does and who wrote it.

Before you install anything, the row tells you what that plugin will be allowed to do, in plain words:

• Can contact api.example.com means it can talk to that one address and nowhere else.
• Can save its own settings and cached data means it gets a small private store on your server.
• Can check whether specific titles are in your library, and never what else is there means it can ask about titles it already knows the name of, one list at a time, and get back only the ones you have. There is no way for it to take an inventory of your library.
• Runs on its own, with no network and no storage means exactly that.

That list is the whole of it. There is no fine print and no second screen of permissions after you press Install.

Press Install. The plugin downloads, gets checked, and starts. If it has settings, they appear as rows on its card.

Settings, and whose they are

Most plugin settings are the server’s: you set them once and they are the same for everyone in the house. Those are the rows on the plugin’s card.

Some settings belong to each person instead. Those do not appear on your card, because they are not yours to set for somebody else. The card names them, and everyone sets their own:

• In the apps (Apple TV, iPhone, iPad, Android phone, Android TV): Settings → Plugins, under Plugin preferences.
• In a browser: your own settings, in the same Plugin preferences section.

Your housemates each get their own, and nobody sees anyone else’s. If no plugin on the server has anything personal to ask, the section is not there at all.

A plugin can also put a button on its card, like “Test connection”. Pressing it runs the plugin and shows you one line back. That is all a button can do: it cannot draw anything, and it cannot ask for anything you have not already given the plugin. A plugin can put a button on the personal screen too, and that one is the only kind that knows which person pressed it.

Connecting your own account

Some plugins work with a service you already have an account with, like a watch-tracking site. Those need each person to connect their own account, and that is deliberately not something an owner can do on somebody’s behalf.

You will find them in the same place as your preferences, under Connected accounts: Settings → Plugins in the apps, or your own settings in a browser. Each one says what it would be told before you decide, for example If you connect it, it will be told what you start, pause and finish watching. Nothing is sent until you do.

Press Connect and you get a short code and a web address to open on your phone or computer. Finish there and the row says who you connected as.

Until you do that, the plugin is never told you exist. There is no server setting that could start it for you, and an owner who installs a scrobbler has not connected anybody to it, including themselves.

Disconnect stops it immediately and makes the server forget the account you connected. Nothing more is sent, whatever the far end does about it.

What a plugin can and cannot do

Every plugin runs in a sandbox inside your server. It has no access to your files, no way to reach your home network, and no way to see another plugin’s data. It gets the permissions above if it asked for them, and nothing else.

A plugin that asks to contact an address can only reach that address on the public internet. It cannot use that permission to reach your router, your NAS, or anything else on your network: those are refused, including when a site tries to redirect it there.

Plugins never run code on your TV, your phone, or in your browser. They hand information to your server, and your server hands it to the apps, which draw it themselves. That is why a plugin works on every screen without anyone writing a version for each one.

Where they come from

Everything in Available comes from our catalog. Each one has been read by a person, signed, and hosted by us.

Your server checks that signature itself before it will install anything, using keys built into the server software. That means the check does not depend on our servers being honest or even being ours: a catalog that has been tampered with fails on your machine and nothing installs.

We also publish a withdrawal list. If a plugin turns out to be doing something it should not, it goes on that list, and every server switches it off on its own, with the reason shown. Your server checks it daily and again whenever you open this page.

Turning one off

Turn off stops the plugin immediately. Its settings and cached data stay, so turning it back on picks up where it left off.

Remove takes it off the server entirely, along with anything it saved.

If a plugin was providing your metadata for a library, turning it off means that library has no matching service until you pick another one. Your server tells you that rather than quietly matching against something else: the whole point of choosing a service is that it is the one that gets used.

A withdrawn plugin shows why it was withdrawn and offers only Remove. It cannot be switched back on or reinstalled.

Updates

When a newer version is in the catalog, the plugin’s row offers Update.

If the new version wants a permission the old one did not have, the row says so before you press it. A new power is a new decision, not something an update quietly carries in.

Updates are never automatic. Nothing about your server changes because we published something.

Installing a plugin you wrote yourself

If you are building a plugin, you can install unsigned packages from a file. This is off unless you turn it on, on the server itself: set MULTIPASS_PLUGIN_DEV=1 and restart. An Install from file control appears on the Plugins card, and your server announces developer mode in its log at every boot.

Leave it off otherwise. It exists so an author can test their own work, and a server with it on will run code nobody has reviewed.

If you want to build one, the developer guide covers writing, packaging and submitting.