On this page
Plug-in manifest reference
Every field of starboard-plugin.json, version 1, with the check Starboard runs on it and why. Starboard refuses
any field it does not know, so a mistake cannot slip through. This page matches plug-in API 1.15.0
(API_VERSION in starboard/plugins.py).
The same rules are in a JSON Schema, starboard/plugin-manifest.schema.json, for editors and other tools. The
check in starboard/plugins.py is what Starboard itself runs, and the plug-in tester
runs it too. For a first plug-in, read Make your first plug-in.
The top level
| Field | Required | What it is | Check |
|---|---|---|---|
manifest_version |
yes | The manifest's format | Must be 1 |
id |
yes | Its id, used in folders, containers and addresses | 3 to 40 lower case letters, numbers and hyphens; starts and ends with a letter or number |
name |
yes | What people read | Text, up to 40 characters |
version |
yes | Its version | A version such as 1.2.0, optionally with -beta.1 |
description |
yes | One sentence about what it does | Text, up to 200 characters |
author |
yes | Your public name | Text, up to 60 characters |
licence |
yes | Its licence | An SPDX licence id, such as MIT |
homepage |
yes | Its page | An https address |
support_url |
yes | Where people report problems | An https address |
starboard_api |
yes | The plug-in API versions it works with | A range such as >=1.0 <2.0, using >=, >, <=, < and =; this Starboard's API must be inside it |
permissions |
yes | What it may do | A list from Permissions; may be empty |
containers |
no | The small apps Starboard runs for it | One to four; none only for a plug-in with only styles |
resources |
no | Memory and processor for each container | Read Resources |
settings |
no | Its settings, drawn by Starboard | Read Settings |
setup_required |
no | It must be set up before it can start | true or false. API 1.4 |
cards |
no | Its dashboard cards | Read Cards |
actions |
no | Its buttons | Read Actions |
health |
no | A path that answers 200 while it works | A path such as /health |
needs |
no | Apps it needs, shown before install | A list of app names such as jellyfin: 2 to 30 lower case letters, numbers and hyphens |
styles |
no | Styles for Display | Read Styles |
notices |
no | Things people must know before install | Read Notices. API 1.4 |
events |
no | Events Starboard sends it | Read Events. API 1.4 |
jobs |
no | Jobs Starboard runs for it | Read Jobs. API 1.4 |
changes |
no | What changed in each version, shown as What is new before and after an update | Read Changes. API 1.10; before the update since API 1.14 |
adopt |
no | An app the main install may already run, which Starboard can copy into the plug-in | Read App plug-ins. API 1.13 |
logo |
no | A small logo, shown in Settings, Plug-ins and on its dashboard cards | Read Logo. API 1.14 |
update |
no | How it updates safely: a step before and after, the health wait and settings migrations | Read Updates. API 1.14 |
jellyfin_libraries |
no | Jellyfin libraries for folders it fills, which Starboard adds with real-time monitoring deactivated | Read Jellyfin libraries. API 1.15 |
Permissions
Each permission is shown in plain words with its risk before anyone adds the plug-in. Ask only for what you use: people read every one, and the plug-in's API key gets only the read permissions it asked for.
| Permission | What people read | Risk | Key scope |
|---|---|---|---|
apps:read |
Your apps and whether they answer | low | apps |
downloads:read |
What is downloading | low | downloads |
media:read |
Your films, series and books (the media folder, read only, and the library) | medium | media |
system:read |
Processor, memory and disks | low | system |
network:lan |
Reach other computers on your home network | medium | none |
network:vpn |
Run inside your VPN connection | medium | none |
jellyfin:key |
Use Jellyfin's API key, kept by Starboard | high | none |
reelix:key |
Use Reelix's API key, kept by Starboard (API 1.6) | high | none |
usenet:servers |
Use your news server's address and sign-in, from NZBGet or SABnzbd (API 1.6) | high | none |
network:port |
Open its own web page on your home network, at a port Starboard chooses (API 1.13) | medium | none |
appearance:styles |
Add styles to Display: colours, corners, a font and shadows, checked for accessibility | low | none |
jellyfin:metadata |
Read and change Jellyfin's metadata folder: the posters, photos and details Jellyfin saved (API 1.14) | medium | none |
jellyfin:libraries |
Have Starboard add its own libraries to Jellyfin, for folders it fills in your media folder (API 1.15) | medium | none |
library:holding |
Move films and series from your library into the holding folder in your media folder, and put them back (API 1.15) | high | none |
The plug-in's risk is its highest permission's risk. Read What a plug-in can change for how this is shown to people.
Containers
Each item in containers is one container. Starboard always calls the first one for cards, buttons, custom
settings, events and jobs.
| Field | What it is | Check |
|---|---|---|
name |
Its short name | Lower case letters, numbers and hyphens, up to 21 characters, different from the others |
image |
Its image | Pinned by digest: registry/name@sha256: and 64 hex characters. Read Security rules |
port |
The port it answers on | 1 to 65535. Starboard uses 80 when it is left out |
network |
Which network it joins | default, lan or vpn. Read Networks |
volumes |
Folders it gets | data, data:<path>, data/<folder>:<path>, media:ro, media:holding (API 1.15), media/<one folder> or media/<one folder>:ro. Read Volumes |
env |
Settings passed as environment variables | Names of letters, numbers and _ (UPPER_CASE before API 1.13; an app such as Tdarr reads serverIP); values text, numbers or true and false. From API 1.13 a value may hold {secret:<name>}, {jellyfin:url} or {jellyfin:key}. Read App plug-ins |
start |
When it runs | always (the default) or when_needed, for the first container only. Read Resting when idle |
idle_stop_minutes |
For when_needed: minutes idle before it rests |
A whole number; 15 when left out |
publish |
Puts port on the home network: on Gluetun for network: vpn (plug-in API 1.9), or as the app's own web page for network: lan (API 1.13) |
true or false; only with network: vpn or lan and a port; on lan it needs network:port |
host_port |
For publish on lan: the port Starboard tries first, usually the app's own, such as 3000 |
1024 to 65535. Starboard takes the next free port when it is in use. API 1.13 |
tmpfs |
Folders in memory the app writes to, such as /var/run/postgresql, owned by its user |
Up to 6 paths inside the container, never /tmp (it always has one) or /run/starboard. Only /run may run programs, for images with s6. API 1.13 |
user |
The user it runs as | uid:gid such as 1000:1000, never root (uid 0); 10001:10001 when left out. From API 1.12, media: the media folder's owner, only for a container that mounts media/<one folder>, from API 1.14 jellyfin-metadata, or from API 1.15 media:holding. Read Adding files to the media folder |
command |
The command it runs | Only plug-ins built into Starboard may set it |
build |
Its image is built by Starboard from the Dockerfile in the plug-in's zip file (API 1.15) |
true or left out. With it, image must be local/<id>:<version>, such as local/on-demand:0.9.2, and the plug-in installs only from a zip file. Read Built from a zip file |
The container's name on the server is plugin-<id>-<name>, such as plugin-hello-card-main.
Networks
| Value | What it reaches | Permission needed |
|---|---|---|
default |
Only Starboard, on the plug-in's own network, which has no way out | none |
lan |
Also your home network and the internet, and the server itself as host.docker.internal |
network:lan |
vpn |
The internet through your VPN: it runs inside Gluetun's network | network:vpn |
Volumes
| Value | Path inside the plug-in | Permission needed |
|---|---|---|
data |
/data, read and write: its own folder, data/plugins/<id>/data/<container name> |
none |
media:ro |
/media, read only: the whole media folder |
media:read |
media/<one folder> |
/media/<one folder>, read and write: one folder in the media folder, such as media/music |
none, but it is listed as something it can change |
media/<one folder>:ro |
/media/<one folder>, read only (API 1.13) |
none; it is listed as something it can read |
data:<path> |
Its own folder, at the path the app expects, such as data:/config (API 1.13) |
none |
data/<folder>:<path> |
A folder inside its own folder, at a path, for an app with several, such as data/server:/app/server (API 1.13) |
none |
jellyfin-metadata |
/metadata, read and write: Jellyfin's metadata folder, its posters, photos and details (API 1.14). Read Jellyfin's metadata folder |
jellyfin:metadata |
jellyfin-metadata:ro |
/metadata, read only (API 1.14) |
jellyfin:metadata |
media:holding |
/media, read and write: the whole media folder, to move items into its holding folder, /media/.holding/<id>, and back (API 1.15). Read The holding folder in the media folder |
library:holding |
Nothing else can be mounted. The folder name after media/ is 1 to 60 letters, numbers, dots, underscores and
hyphens, so it cannot climb out with ...
Jellyfin's metadata folder
From API 1.14, a plug-in that works on the pictures and details Jellyfin keeps, such as one that shrinks posters,
mounts Jellyfin's metadata folder with jellyfin-metadata (read and write) or jellyfin-metadata:ro (read only),
and asks for the permission jellyfin:metadata. Nothing else gets the folder: without the permission the manifest is
refused, and the folder is mounted only for a plug-in that was granted it.
- In the container it is always
/metadata. On the server, Starboard finds it where Jellyfin mounts it:/metadataon new installs (${CONFIG_DIR}/jellyfin-metadata), or Jellyfin's ownconfig/data/metadataon an install that has not been moved yet. When Jellyfin is not installed, the plug-in cannot be added, and Starboard says so. - To change files there, run the container as
"user": "media", the apps' own user, which owns Jellyfin's files. - People read before they add it: "Jellyfin's metadata folder: the posters, photos and details Jellyfin saved. It can change, replace and remove them, and Jellyfin shows what it leaves there". Its risk is medium.
- Check each file before it replaces the one Jellyfin saved, and keep the work slow and quiet: Jellyfin reads these files while people watch.
"permissions": ["jellyfin:metadata"],
"containers": [{"name": "main", "image": "ghcr.io/you/picture-shrinker@sha256:...", "port": 8080,
"volumes": ["data", "jellyfin-metadata"], "user": "media"}]
Built from a zip file
From API 1.15, a private plug-in with no registry, such as On demand, can ship its own image as a Dockerfile in a
zip file. People add it in Settings, Plug-ins, Add a plug-in, Upload a zip file; a newer zip updates
it from its page, with Update from a zip file. A plug-in with build cannot be added from an address or a
catalogue, because there is nothing to build from.
"containers": [{"name": "on-demand", "image": "local/on-demand:0.9.2", "build": true, "port": 7790,
"volumes": ["data", "media/on-demand"], "user": "1000:1000"}]
The zip. starboard-plugin.json and Dockerfile at the top of the zip, not in a folder inside it. Up to 50 MB,
unpacking to at most 200 MB in at most 2,000 files. Only files and folders: no links, devices or pipes, no names that
climb out with .. or start with /, no backslashes, no two files with the same name, and nothing encrypted.
The Dockerfile. It may build from public images and the zip's own files, and nothing more:
- no parser directives such as
# syntax=(they would run someone else's builder); - no
RUN --mount,--networkor--security; - no
ADDfrom the internet or git, andCOPY --fromonly from an earlier stage of the same Dockerfile; - no
VOLUMEorONBUILD; FROMnames its image in full (no variables), never an image built on the computer (local/...), at most 6 times.
The build. Docker's own builder, with up to 2 GB of memory (and no swap beyond it), 2 processor cores and 20
minutes. The build can reach the internet to fetch what the Dockerfile names, never the server's own network, folders,
Docker or other apps. No build arguments or secrets are passed. An image over 3 GB is refused. The image is tagged
local/<id>:<version>, so Roll back finds the version before without a download, and Starboard keeps the zips of
the current and the previous version beside the plug-in, so an image that has gone is built again on Activate.
People read before they add it: "Starboard builds its image, local/on-demand:0.9.2, from the Dockerfile in the zip",
with the limits and the image it starts from. Make the zip from your committed files, as On demand's
tools/make-zip.sh does with git archive.
The holding folder in the media folder
From API 1.15, a plug-in that tidies the library, such as Library clean-up, can move films and series out of it and
put them back. It asks for the permission library:holding and mounts media:holding: the whole media folder, read
and write, at /media. Without the permission the manifest is refused.
- What it moves goes in
/media/.holding/<plug-in id>/, keeping the folders it was in, so/media/movies/A Film (2001)becomes/media/.holding/library-cleanup/movies/A Film (2001)and can go back to the same place. The holding folder is inside the media folder because a move between two folders Docker mounts separately is a copy and then a delete, even on one disk; inside one mount it is a rename, which is instant and needs no free space. Its name starts with a dot and it is outside every library folder, so Jellyfin and Reelix do not list what is in it. - Never delete. The folder is mounted read and write, so Starboard cannot stop a plug-in that deletes; people read that before they add it, and the collection's tests check that its code has no way to delete a media file.
- Offer Put back for each item: a row with the
restoreaction on a custom setting's list (API 1.15), and say first, with a preview, what would move and how much space it frees. - Tell Reelix (with
reelix:key) to stop following what moves, so it is not downloaded again, and to follow it again when it is put back; tell Jellyfin (withjellyfin:key) the folder has gone, and that it is back. - Run the container as
"user": "media", the owner of the media folder, so moved folders keep their owner. - People read before they add it: "Your media folder: it can move films and series into the holding folder there (media/.holding) and put them back. It is given the whole folder to read and change, so add only a plug-in you trust; what it moves leaves Jellyfin until it is put back". Its risk is high.
"permissions": ["jellyfin:key", "reelix:key", "library:holding", "network:lan"],
"containers": [{"name": "main", "image": "ghcr.io/you/library-cleanup@sha256:...", "port": 8080, "network": "lan",
"volumes": ["data", "media:holding"], "user": "media"}]
Adding files to the media folder
A container that adds files to media/<one folder>, such as a sound track next to a film in media/movies, needs to
write as the folder's owner. From API 1.12, give it "user": "media":
- It runs as the media folder's owner, the apps' user and group from Install apps (1000:1000 when Starboard does not know them), never root.
- Before it starts, Starboard makes each
media/<one folder>it mounts that is missing, owned by the user it runs as. A folder that is there already is left as it is. - People read, before they add it, the folders it can change and that it runs as the media folder's owner.
Ask for the fewest folders you need. Never delete the person's files: move them to a folder of your own and let them delete it.
Security rules
Starboard writes each plug-in's Compose file itself, data/plugins/<id>/compose.yaml, and the plug-in cannot change
what it writes. Each rule is there for one reason.
- Images pinned by digest. A tag such as
:latestcan point at different code tomorrow. A digest cannot, so what people approved is what runs. The tester's development box allows a tag only while you test. - No Docker socket, no privileged mode, no devices, no host network. Any of these would give the plug-in control of the whole computer. No manifest field can ask for them.
- Only these volumes. A plug-in reaches its own folder and, if allowed, the media folder. It never reaches other apps' settings or Starboard's own data.
- Never root.
usermust not be uid 0. A program running as root inside a container is one mistake away from root on the server. - Read only, with no extra rights. Every container runs with a read-only file system and a 64 MB
/tmp, every Linux capability dropped, no new privileges, and at most 64 processes (an app plug-in may ask for up to 1024 withpids, API 1.13). - Its own network. With
default, the plug-in reaches Starboard and nothing else.
Resources
resources maps a container's name to its limits:
"resources": {"main": {"memory": 256, "cpus": 0.5}}
| Field | What it is | Default | Ceiling |
|---|---|---|---|
memory |
Memory in MB | 128 | 512 |
cpus |
Processor cores | 0.25 | 1.0 |
pids |
Processes and threads, for an app such as Kavita or Tdarr (API 1.13) | 64 | 1024 |
The ceilings keep Starboard light on small servers, such as a Raspberry Pi. Each container's limits are shown to people before they add the plug-in.
App plug-ins
From API 1.13 (DASH-411) a plug-in can be a whole app that is kept out of the main install, such as Jellystat with its PostgreSQL database, or Navidrome. Starboard still writes its Compose file and every security rule on this page still applies: the app runs read only, as a user that is not root, with no capabilities.
- An app and its database. Up to four containers share the plug-in's own network, which reaches nothing else.
Each reaches the others by its container name,
plugin-<id>-<name>, such asplugin-jellystat-db. - Its web page. A container on
lanwithpublish: trueand aportis opened on the home network. It needsnetwork:port, which is shown to people before they add it. Starboard chooses the port on this computer:host_portif it is free, otherwise the next free one, avoiding ports other containers, other plug-ins and Starboard's own apps use. If something outside Docker holds it, the start fails and Starboard takes the next port and tries again. The port is kept, so it stays the same after an update or a Roll back. Starboard shows the address on the plug-in's page, with Open, and on Your plug-ins. - Passwords made for the install.
{secret:db_password}inenvis a random value Starboard makes once for this install and keeps owner-only indata/plugins/<id>/secrets.json. Use the same name in the app and its database. - Jellyfin's address and key. With
jellyfin:key,{jellyfin:url}and{jellyfin:key}inenvare filled in from Starboard's Jellyfin each time the plug-in starts, asrun/jellyfin.jsonis. - Data where the app wants it.
data:/configmounts the container's own folder at/config;data/server:/app/servermounts a folder inside it.tmpfsgives folders in memory, such as/var/run/postgresql. - Removing it. Removing any plug-in keeps its folder. People choose where it goes: kept in
data/plugins/.removed, or moved to the holding folder in System, Clean up, from where they can put it back or delete it for good. - Taking over an app.
adoptnames an app the main install may run, so Starboard can copy its settings into the plug-in:
"adopt": {"app": "tdarr", "name": "Tdarr", "into": "server", "stop": true,
"copy": {"/app/server": "server", "/app/configs": "configs", "/app/logs": "logs"}}
| Field | What it is |
|---|---|
app |
The app's container name in the main install |
name |
What people read, up to 40 characters |
into |
The plug-in's container whose data folder gets the copies |
copy |
One to eight folders: the folder inside the app, and the folder inside data/plugins/<id>/data/<into> it is copied to |
stop |
true to stop the app first, so its files are copied whole and its port is free. It is stopped, never removed |
Starboard copies with the app's folders mounted read only, so they are never moved, changed or deleted. Anything the
plug-in already wrote there is put beside, as <folder>.before-copy-<date>. The plug-in must be inactive. Only folders
the app keeps on the computer (bind mounts) can be copied; a Docker volume is said plainly. Afterwards the person
removes the app from the main install themselves, in Settings, Install apps.
In a catalogue entry, rest says what the app uses at rest, measured: {"memory_mb": 117, "cpu_percent": 0.22}.
Starboard shows it under the plug-in in the catalogue, so people with a small server can choose.
Jellyfin libraries
From API 1.15, a plug-in that fills folders for Jellyfin, such as On demand's films and series, names its libraries
in jellyfin_libraries and asks for jellyfin:libraries. Starboard adds each one Jellyfin does not have when the
plug-in is activated, and checks them again on every activation, so after each install, update and Roll back.
"permissions": ["jellyfin:libraries"],
"jellyfin_libraries": [
{"name": "On demand Films", "type": "movies", "folder": "media/on-demand/films"},
{"name": "On demand TV", "type": "tvshows", "folder": "media/on-demand/tv"}
]
| Field | Required | What it is | Check |
|---|---|---|---|
name |
yes | The library's name in Jellyfin | Text, up to 40 characters, different from its other libraries |
type |
yes | What it holds | movies, tvshows, music, books, homevideos, musicvideos or mixed |
folder |
yes | Its folder | Inside a media folder one of its containers mounts, such as media/on-demand/films, up to 3 folders deep |
realtime_monitor |
no | Whether Jellyfin watches the folder for new files | true or false; false when left out |
- Real-time monitoring is deactivated unless you set it. Jellyfin watching a folder costs one of the computer's folder watches for every folder in it, and a large library can use them all up before the person's own Films and TV. A plug-in that adds files itself tells Jellyfin to check (a library refresh) instead.
- Starboard keeps it as you set it. Someone who activates monitoring in Jellyfin finds it deactivated again on the next activation of the plug-in. Nothing else about the library is changed.
- Found by its folder, then by its name. A library Jellyfin already has, from an older version or made by hand, is used, not added twice.
- The folders are made first, owned by the container's user, because Jellyfin will not add a folder that is not there.
- They stay when the plug-in is removed. They are the person's to keep or remove in Jellyfin.
- Never a stop. When Jellyfin is not connected or does not answer, the plug-in still starts, and its state says what went wrong.
People read before they add it: "Jellyfin: Starboard adds 2 libraries On demand Films and On demand TV, for folders it fills in your media folder. Real-time monitoring is deactivated for On demand Films and On demand TV, as the plug-in refreshes them itself."
Settings
Starboard draws a plug-in's settings in its section of Settings, then Plug-ins, checks each value, and saves
them in the plug-in's settings.json. Read Settings and key files.
| Field | What it is |
|---|---|
key |
Its name in settings.json: lower case letters, numbers and underscores, starting with a letter, up to 41 characters. Required |
label |
What people read. Required. Keep it under 60 characters, in sentence case, with no colon |
type |
One of the types listed in this section. Required |
hint |
One sentence under the field |
default |
Its value when the plug-in is added, or when an update adds the setting |
min, max, unit |
For number |
choices |
For choice: the list to choose from, each a value such as "eng" or, from API 1.5, {"value": "eng", "label": "English"} so people read words, not codes. For custom: the path that gives its choices |
required |
true when the plug-in cannot start without it. API 1.4 |
group |
The section it goes in, such as Picture and sound: up to 40 characters, in sentence case. Settings without one go in Settings. API 1.5 |
restart, item |
Accepted, reserved for later |
| Type | What people get | What Starboard checks |
|---|---|---|
text |
A text box | Up to 500 characters |
number |
A number box | A number from min to max |
switch |
Activate or deactivate | Saved as true or false |
choice |
A list | One of choices |
address |
An address box | An address Starboard is allowed to call |
secret |
A password box | Never sent back to the browser; shown as set or not set. Up to 2000 characters |
folder |
Browse, inside what the plug-in mounts | A folder inside /media or /media/<one folder>. Needs a container that mounts media:ro or media/<one folder>. API 1.3 |
list |
A box with one value a line | Saved as a list of strings, blank lines left out. Up to 200, each up to 500 characters |
custom |
A list the plug-in describes, drawn by Starboard | choices is a path on the plug-in. Read Custom pages |
schedule |
How often (every day, every week or every month), the day or the date, and a time, side by side | Every day, week or month; a day of the week for a week; a date from 1 to 31 for a month; a time such as 03:30. A month without the date runs on its last day. API 1.14. Read A job on a schedule from its settings |
Setting up before it starts
- A setting with
"required": trueand no value keeps the plug-in in theneeds-setupstate, and Starboard says which settings are missing. "setup_required": truekeeps it there until its settings have been saved once with nothing required missing.- People are told before install that it needs setting up.
Both came in API 1.4. Read States.
How Starboard lays them out
Starboard draws every plug-in's settings the same way, as Starboard's own Settings pages are drawn:
- Each
groupis its own section, with a topic tab, in the order the groups first appear. Settings with no group come first, under Settings. Use groups once a plug-in has more than about six settings. - Switches, choices, numbers and folders save as soon as they change, with Saved at and the time beside them.
- Text, addresses, secrets, lists and required numbers are one form per section with one Save at its foot.
- The plug-in's
actionsare buttons in an Actions section, after its settings and pages.
Cards
Each item in cards is a card people can add with Edit dashboard. Read
Card answers for what the path answers.
| Field | What it is | Check |
|---|---|---|
id |
Its id, in the card's address | Letters, numbers, hyphens and underscores, up to 40. Give every card one |
title |
Its name on the dashboard | A card needs a title (or a label), so a screen reader can name it |
titles |
Its title for each card size, so it fits on one line in that size: any of small, medium, half, wide and full |
Each one line of words, up to the size's limit: small 17, medium 28, half 22, wide 43 and full 45 characters. A size left out shows the plug-in's name with the card's title under it. Read A title for each size. API 1.15 |
type |
stat, list, status or, from API 1.8, guide |
Required |
path |
The path on the first container that answers | Required: starts with /, up to 80 letters, numbers, /, _, . and - |
format |
For stat: number, bytes, percent, duration (seconds) or date (seconds since 1970) |
number when left out |
label |
Another name for the card | Optional |
example |
What the path answers | The tester checks its shape, and warns when it is missing |
refresh_minutes |
How often Starboard asks | Minutes between asks, 1 to 1440; 1 when left out. Starboard never asks more often than once a minute, unless the card has refresh_seconds. API 1.4 |
refresh_seconds |
How often the dashboard asks, in seconds, such as 30 for a card that shows progress |
A whole number from 10 to 3600. 10 seconds is the quickest any card is asked. The card's answer may give its own refresh_seconds, which wins, so a setting can change it. Left out, the card is asked as before, once a minute or every refresh_minutes. API 1.14 |
"cards": [
{"id": "now", "title": "Direct play", "type": "list", "path": "/card", "refresh_seconds": 30}
]
A card with refresh_seconds is asked again at that time while its dashboard is open and in view, never while the
browser tab is hidden. Cards due at the same time are asked in one request. Read
How often a card is asked.
From API 1.14 Starboard draws every plug-in card with a grey band across the top: the plug-in's logo (or
its initials), the plug-in's name as the card's heading, the card's title under it when it differs, and at the
right a status chip and when it last updated, from the card's answer. You do not lay any of it out. Read
The card band.
A title for each size (API 1.15)
People choose each card's size in Edit dashboard: small (a quarter of the width), medium (a third), half, wide
(two thirds) or full width. From API 1.15 a card can have its own title for each size in titles, so a small card
has a short title and a wide one can say more. The title for the card's size is then the card's heading on its own,
on one line beside the logo, and screen readers hear the plug-in's name after it when the title does not say it. A
size you leave out shows the plug-in's name with the card's title under it, as before.
| Size | Up to | Measured at its narrowest |
|---|---|---|
small |
17 characters | A quarter of the width, in a window 1101 pixels wide. The chip (its icon only) and the time sit under the title |
medium |
28 characters | A third of the width, 1101 pixels. The chip and the time sit under the title, as they do not fit beside it |
half |
22 characters | Half the width, 1101 pixels, with the chip and the time beside it |
wide |
43 characters | Two thirds of the width, 1101 pixels, with the chip and the time beside it |
full |
45 characters | The whole width, in a window 768 pixels wide, with the chip and the time beside it |
"cards": [
{"id": "saved", "title": "Space saved", "type": "stat", "path": "/card", "format": "bytes",
"titles": {"small": "Space saved", "medium": "Picture space saved", "half": "Pictures: space saved",
"wide": "Space saved by shrinking pictures", "full": "Space saved by shrinking posters and photos"}}
]
Each limit is what fits on one line in the card's band, beside the logo, the status chip and the time, at the standard text size in the narrowest window that size is shown at, measured with wide words. On a small card the chip shows only its icon (screen readers still hear its words), and the chip and the time sit under the title; on a medium card they sit under it in windows 1101 pixels wide and wider, where they do not fit beside it. When someone makes the text larger in Display, a title may take two lines; Starboard never cuts a title short. The manifest check refuses a title longer than its size's limit, and the plug-in tester names it with its limit. Keep the words that matter first, and write each title in sentence case.
Actions
Each item in actions is a button in the plug-in's section of Settings, then Plug-ins. Read
Actions for what Starboard sends.
| Field | What it is |
|---|---|
id |
Its id: letters, numbers, hyphens and underscores, up to 40. Give every button one. A button without one is known by its place in the list, counting from 0, which changes when you move it |
label |
The words on the button, saying what it does, such as Run Live TV now. Required |
path |
The path on the first container that Starboard sends a POST to. Required |
confirm |
A question Starboard asks before the button runs, such as Downloads a test file now. Continue?, in its standard confirm box. The box starts on Cancel, and Escape cancels. Up to 300 characters |
Health
health is a path, such as /health, that answers 200 while the plug-in works. Keep it cheap: no calls to other
apps. The tester warns when a plug-in with containers has none. Starboard asks it when Settings, then
Plug-ins, is opened, and shows Not answering when it does not answer 200. For plug-ins built into
Starboard, it is also the container's health check. After an update, Starboard waits for it to answer before it
keeps the new version (API 1.14): read Updates.
Styles
styles lists 1 to 32 styles for Display (16 before API 1.2), and needs the permission appearance:styles.
Each style has an id, a name, and a light and a dark set of colours. Starboard checks every style for
contrast in light and dark before it can be added. A plug-in with only styles runs no container. Read
Styles in Write a plug-in, and the JSON Schema for every style field.
Notices
notices lists what people must know before they add the plug-in. Each is shown with the install warning. API 1.4.
| Notice | What people read |
|---|---|
p2p |
Shares files with other people over the internet, which can show your internet address |
adult |
Has adult content |
Events
events lists the events Starboard sends the plug-in. Each needs the read permission that already covers what it
tells, and a container to send it to. API 1.4. Read Events for what each one
sends.
| Event | When | Permission needed |
|---|---|---|
item.added |
When something new arrives in your library | media:read |
download.finished |
When a download finishes | downloads:read |
app.down |
When one of your apps stops answering | apps:read |
app.up |
When one of your apps answers again | apps:read |
playback.started |
When someone starts playing something | media:read |
request.available |
When something someone asked for is ready to watch. API 1.11 | media:read |
download.failed |
When a download stops with a problem. API 1.11 | downloads:read |
disk.nearly_full |
When a disk is nearly full. API 1.11 | system:read |
update.available |
When an update is ready for Starboard, an app or a plug-in. API 1.11 | apps:read |
Jobs
jobs lists up to eight jobs that Starboard runs for the plug-in on its own clock. They need a container to run
in. API 1.4. Read Jobs for what Starboard sends.
| Field | What it is | Check |
|---|---|---|
id |
Its id | Lower case letters, numbers and hyphens, starting with a letter, up to 31; different from the others |
label |
What people read in System, then Jobs | Required, up to 60 characters |
path |
The path on the first container | Required |
daily |
A time each day, such as 03:30 |
Give exactly one of daily, every_hours, at_start and schedule |
every_hours |
Every so many hours | A whole number from 1 to 168 |
at_start |
Once each time Starboard starts | Must be true |
schedule |
When the person chooses, in one of its settings | The key of one of its settings of type schedule. API 1.14 |
time_limit_minutes |
How long it may take | 1 to 120; 10 when left out |
quiet_hours |
Run only in quiet hours | true or false |
"jobs": [
{"id": "tidy", "label": "Tidy old files", "path": "/jobs/tidy", "daily": "03:30", "time_limit_minutes": 20, "quiet_hours": true}
]
A job on a schedule from its settings
From API 1.14 a job can run when the person chooses rather than at a time you fixed: every day, every week on a
chosen day, or every month on a chosen date, at a chosen time. Add a setting of type schedule, with a default, and
name its key in the job's schedule:
"settings": [
{"key": "when", "label": "When to shrink", "type": "schedule", "hint": "It runs at this time.",
"default": {"every": "week", "day": "sunday", "time": "03:30"}}
],
"jobs": [
{"id": "shrink", "label": "Shrink pictures", "path": "/jobs/shrink", "schedule": "when", "time_limit_minutes": 120}
]
| Value | What it is |
|---|---|
every |
day, week or month. Required |
time |
The time, such as 03:30, in the server's own time zone. Required |
day |
For week: monday, tuesday, wednesday, thursday, friday, saturday or sunday |
date |
For month: 1 to 31. In a month without that date, such as the 31st in April, it runs on the month's last day |
- Starboard draws the setting as How often, then Day or Date, then Time, and saves each change at once. It checks the value, says what is wrong in plain words ("When to shrink: needs a day of the week"), and keeps only the parts the schedule uses.
- The job runs within 5 minutes after its time. If the server was off then, it still runs up to 6 hours late, and otherwise waits for the next time, so it never starts in the middle of the day by surprise.
- System, then Jobs, says the schedule in words and when it runs next, such as "Every week on Sunday at 03:30, next Sunday 16 November at 03:30", with Run now as for any job.
- The install warning says the job runs on the schedule people choose, and what it starts with.
- Without a usable value or default, the job does not run by itself; Run now still works.
- With
quiet_hours, it runs only when its time falls in quiet hours.
Logo
From API 1.14 a plug-in may have a small logo: an SVG or PNG file next to starboard-plugin.json. Starboard shows it
in Settings, Plug-ins (Manage and the Catalogue), on the plug-in's own page, and in the grey band of
each of its dashboard cards. A plug-in without one gets its initials on a plain tile, so every card has the same layout.
"logo": {"file": "logo.svg", "alt": "A play symbol on a screen"}
| Field | What it is | Check |
|---|---|---|
file |
The file's name, next to the manifest or in one folder under it, such as logo.svg or images/logo.png |
Ends in .svg or .png; no .. |
alt |
What the logo shows, in words, for people who cannot view it | 3 to 80 characters, such as "A play symbol on a screen". Not the plug-in's name: that is always beside it |
How Starboard reads it:
- When the plug-in is added or updated from an address (or the catalogue), Starboard fetches the file from beside the manifest, checks it, and keeps a cleaned copy in the plug-in's folder. It serves that copy itself; the browser never loads anything from your site. A manifest pasted into Test a plug-in has no address, so its logo cannot be read.
- SVG: up to 16 KB, with a
viewBox; only shapes, paths, groups, gradients,useof its own parts,titleand text. No scripts,foreignObject, pictures,styleelements or attributes, animation, event handlers (on...), links outside the file orurl()other thanurl(#id), and no DOCTYPE or entities. Starboard draws the SVG again from what it allows. - PNG: up to 32 KB, square, from 32 to 256 pixels a side.
- It is shown at 32 and 40 pixels: use one solid shape that reads at that size in light and dark.
- A logo that fails a check is not used: the plug-in is still added, with its initials, and the plug-in tester reports it as a warning with what to change.
- Roll back brings back the logo of the version before.
A catalogue entry can carry the same logo for the Catalogue, before anything is added. Read Catalogues.
Updates
update tells Starboard how to update the plug-in safely. Every part is optional. API 1.14. Read
Write a plug-in that updates safely for a walk through.
| Field | What it is | Check |
|---|---|---|
before |
A step Starboard calls on the version that is installed, before anything changes: finish or pause work | {"path": "/update/before", "time_limit_seconds": 60}. The path starts with /; the time limit is 5 to 300 seconds, 60 when left out. Needs a container |
after |
A step Starboard calls on the version running at the end: tidy up or start work again | The same as before |
health_wait_seconds |
How long Starboard waits for the new version's health path to answer 200 |
10 to 600, 60 when left out. Needs health |
migrations |
How saved settings move from older versions | 1 to 20 steps, each in this section |
Each step of migrations:
| Field | What it is | Check |
|---|---|---|
version |
The version that made the change | Required. A version such as 2.0.0, different from the others, no newer than the manifest's version |
rename |
Old setting keys and their new keys | Up to 20. The new key must be one of this version's settings |
remove |
Setting keys this version no longer has | Up to 20. A key still in settings is refused, unless a later step renames something to it |
defaults |
New default values | Up to 20. The key must be one of this version's settings |
Give at least one of rename, remove or defaults in each step.
What Starboard does, in order:
- Before. If the plug-in is active and the installed version has
before, Starboard sends itPOSTwith{"from": "1.0.0", "to": "2.0.0"}. An answer other than 2xx,{"ok": false, "said": "..."}, or no answer within the time limit stops the update, and nothing is changed. The words insaidare shown. - Settings. Each migration step whose
versionis later than the installed version and no later than the new one is applied, oldest first.renamemoves a value to its new key (a value already under the new key wins).removedrops a key.defaultssets a new value only where the saved value is still the installed version's default, or there is none, so a value someone chose is kept. A new setting then gets itsdefault. - Install. The new manifest, settings and Compose file are written, the version before is kept in
previous/with its settings as they were, and an active plug-in starts on the new version. - Health. Starboard asks
healthevery 3 seconds, for up tohealth_wait_seconds. If the new version does not start or does not answer 200 in time, Starboard rolls back by itself: the version before, with its settings as they were, and itsafterstep hears{"outcome": "rolled_back"}. - After. The new version's
afterstep hears{"from": "1.0.0", "to": "2.0.0", "outcome": "updated"}. A failingafterdoes not undo the update; it is said in the result and the log.
A plug-in that is not active is updated without its steps or the health wait. Roll back calls before on the
version running and after on the one brought back, with {"outcome": "rolled_back"}, and puts back the settings
kept from before the update. Settings changed since the update are not kept by a Roll back.
"update": {
"before": {"path": "/update/before", "time_limit_seconds": 60},
"after": {"path": "/update/after"},
"health_wait_seconds": 90,
"migrations": [
{"version": "1.5.0", "rename": {"minutes": "every_minutes"}},
{"version": "2.0.0", "remove": ["old_mode"], "defaults": {"every_minutes": 30}}
]
}
A plug-in made for an earlier API has no update: it is updated as before, and Starboard still waits up to 60 seconds
for its health path when it has one, and goes back by itself if it does not answer.
Changes
changes lists what changed in each version, newest first, in the types of
Keep a Changelog. Copy the lines from your CHANGELOG.md. Before an update,
the warning shows What is new since the installed version, from the new version's changes (API 1.14). After an
update, a Roll back or an update from an address, the plug-in's State shows What is new with the versions between the
one people had and the one they have now: each type's first line, and All changes for the rest. It stays until
someone chooses Got it, which Starboard keeps, so it is not shown again on any device. API 1.10.
| Field | What it is | Check |
|---|---|---|
version |
The version these changes are in | Required. A version such as 1.2.0, different from the others |
date |
When it was released | A date such as 2026-11-13 |
added, changed, deprecated, removed, fixed, security |
The changes of that type | Give at least one. Each lists 1 to 20 lines of up to 300 characters |
Up to 20 versions. A line may use **bold** and `code`; Starboard shows them as text, never as HTML.
Start each line with what people notice, in a few words. Include the manifest's own version: the tester warns when
it is missing, because What is new then cannot say what changed. Say when settings move.
"changes": [
{"version": "1.1.0", "date": "2026-11-12", "added": ["**Three new styles:** Sunset, Graphite and Editorial"],
"fixed": ["A style chosen on a phone is kept after Starboard restarts"]},
{"version": "1.0.0", "date": "2026-11-10", "added": ["The first ten styles"]}
]
What each API version added
| Version | Date | Added |
|---|---|---|
| 1.0 | 10 November 2026 | The manifest, containers, permissions, settings, cards, actions, health, needs and styles (up to 16) |
| 1.1 | 11 November 2026 | Styles may set more colours, a heading font and weight, and the focus width |
| 1.2 | 12 November 2026 | Styles may also set card, button, border, tab, header, side menu and chip styles; up to 32 styles |
| 1.3 | 12 November 2026 | The folder setting: a folder inside the media folders the plug-in mounts, chosen with Browse |
| 1.4 | 12 November 2026 | required settings, setup_required, notices, events, jobs and card refresh_minutes |
| 1.5 | 12 November 2026 | A setting's group, and choices with a label |
| 1.6 | 12 November 2026 | The reelix:key and usenet:servers permissions, with /run/starboard/reelix.json and /run/starboard/usenet.json |
| 1.7 | 13 November 2026 | Sub menus in a custom setting's list: menus, and menu on its items and switches |
| 1.8 | 13 November 2026 | Sections with tables in a custom setting's list, selecting several, guides, and notices with progress |
| 1.9 | 13 November 2026 | publish on a container with network: vpn |
| 1.10 | 13 November 2026 | changes: what changed in each version, shown as What is new after an update |
| 1.11 | 13 November 2026 | Four more events (request.available, download.failed, disk.nearly_full, update.available), and readonly on a custom setting's list with folds |
| 1.12 | 13 November 2026 | "user": "media" on a container that mounts media/<one folder>; link and state_label on a custom setting's item; file_only on its add box |
| 1.13 | 13 November 2026 | App plug-ins: network:port and publish on lan with host_port, {secret:...} and {jellyfin:...} in env, tmpfs, data:<path> and media/<one folder>:ro, pids, and adopt |
| 1.14 | 14 November 2026 | A card's own refresh time, refresh_seconds, in the manifest and in its answer, 10 seconds at the quickest; recommended on a catalogue entry; logo (and logo, logo_alt on a catalogue entry); every card drawn with a grey band holding the logo, the name, a status chip and when it last updated (status, status_label and updated in its answer); a schedule setting and a job's schedule; the jellyfin:metadata permission with the jellyfin-metadata volume; update (a before and an after step, health_wait_seconds and settings migrations), with the health wait and an automatic Roll back after every update, and What is new shown before an update too |
| 1.15 | 15 November 2026 | build on a container, for an image Starboard builds from the Dockerfile in the plug-in's zip file, installed with Upload a zip file and updated with Update from a zip file; jellyfin_libraries with the jellyfin:libraries permission; the library:holding permission with the media:holding volume (the media folder, read and write, for its holding folder media/.holding/<id>), and restore on a custom setting's item, drawn as Put back; titles on a card, a title for each card size that fits on one line in that size |
Use the lowest version that has what you use in starboard_api, such as ">=1.4 <2.0" for a plug-in with jobs.
Read API changelog.
Find out more
This page on GitHub, where the help is written.