On this page
Write a plug-in
A plug-in is a folder with one file Starboard reads, starboard-plugin.json, called the manifest. It says what the
plug-in is, what it adds and what it may do. You do not change Starboard's code, and Starboard draws everything a
person reads. What a plug-in can and cannot do is in What a plug-in can change.
What a plug-in can add
- Styles for Display: colours, corners, shadows and a font. No container needed.
- Dashboard cards that show a number, a short list or a status from your plug-in.
- Settings and buttons in its own section of Settings, then Plug-ins.
- Containers: small apps Starboard runs for it, each in its own locked-down space.
The manifest
Every manifest has these fields:
{
"manifest_version": 1,
"id": "hello-card",
"name": "Hello card",
"version": "0.1.0",
"description": "Shows one number on your dashboard.",
"author": "Your public name",
"licence": "MIT",
"homepage": "https://example.invalid/hello",
"support_url": "https://example.invalid/hello/issues",
"starboard_api": ">=1.0 <2.0",
"permissions": ["apps:read"]
}
id uses lower case letters, numbers and hyphens. permissions lists what it may do; people read each one, with
its risk level, before they add it. The full list is in What a plug-in can change.
Styles
Add "appearance:styles" to permissions and a styles list. Each style has a light and a dark set of 13
colours, written as #rrggbb:
bg, header, surface, surface_raised, surface_sunken, text, text_muted, border, divider, accent,
accent_text, accent_soft and focus.
It can also set radius (0 to 24), font (hyperlegible, system, rounded, serif or mono) and shadow
(none, soft or strong). Starboard checks every style in light and dark before it can be added: text needs a
contrast of at least 4.5 to 1 with what is behind it, and borders and the focus ring 3 to 1 (WCAG 2.2). The Styles
plug-in in The plug-in collection is a full example to copy.
Dashboard cards
What cards are for
A card puts one small piece of your plug-in on the dashboard, next to Starboard's own cards: how many titles it has, the last few things it did, or whether it is working. People add your card with Edit dashboard, choose its size and move it. Use a card for something worth knowing at a glance. Long lists, settings and anything people act on belong in the plug-in's own section of Settings, then Plug-ins. Read Use and change the dashboard for how people add cards.
A folder setting
A setting of type folder lets people choose a folder for your plug-in with Browse, as they do everywhere else in
Starboard. It needs plug-in API 1.3 ("starboard_api": ">=1.3 <2.0") and a container that mounts the media folder,
media:ro, or one folder in it, media/<folder>. The folder is always inside what you mount, and your plug-in reads
it by its path inside the plug-in, such as /media/music. Nothing outside the media folder can be chosen.
The three kinds
| Kind | Shows | Use it for |
|---|---|---|
stat |
One number, with a label and a short note | A count, a size, a percentage, a time |
list |
Up to 10 rows, each a title, a detail and an optional link | The latest few items |
status |
OK, Warning or Problem, with one sentence | Whether something is working |
How to write one
- Add the card to the manifest.
pathis a page on your plug-in's first container that answers with JSON.exampleis what that page answers; the tester checks it.
"cards": [
{"id": "count", "title": "Hello", "type": "stat", "path": "/card", "format": "number",
"example": {"value": 42, "label": "hellos", "note": "3 today"}}
]
- Make the path answer in the shape for its kind:
stat:{"value": 42, "label": "hellos", "note": "3 today"}.valueis a number.formatsays how to show it:number,bytes,percent,duration(seconds) ordate(seconds since 1970).list:{"items": [{"title": "Dune", "detail": "Added today", "link": "https://example.invalid/dune"}]}.status:{"state": "ok", "text": "Up to date"}.stateisok,warningorproblem.
- Test the plug-in. Read Test your plug-in.
What Starboard does with your answer
- It asks your path at most once a minute, and only while someone has a dashboard with your card open.
- It waits 3 seconds at most and reads 64 KB at most.
- It shows your text as text, never as HTML, and cuts it to length: labels 40 characters, notes 80, list titles 80, details 120 and status text 160.
- Links must start with
http://orhttps://, and open in a new tab. - If your page does not answer, or answers the wrong shape, the card says "No answer from" your plug-in.
- From plug-in API 1.14, it draws every plug-in card with a grey band across the top: your logo (or your plug-in's
initials), your plug-in's name as the heading, and at the right a status chip, with when it last updated in a lighter footer. Add
statusandupdatedto your answer to fill them, and a smalllogoto the manifest. Read The card band and Logo.
When you make a new version
People update your plug-in from its page, after reading what is new. From plug-in API 1.14, the manifest can make
that safe: changes says what is new, update.migrations moves settings you renamed or removed, update.before
lets the plug-in finish its work first, and Starboard waits for its health path and goes back by itself if the new
version does not answer. Read Write a plug-in that updates safely.
Test your plug-in
In Settings, then Plug-ins, under Test a plug-in, choose your starboard-plugin.json and select Test it.
On a computer with Starboard's files, run python3 -m starboard.plugin_tester path/to/your-plugin. Each issue says
where it is, what is wrong and how to fix it:
- Errors stop the plug-in being added.
- Warnings should be fixed.
- Tips are worth reading.
Accessibility is always tested. It covers every style in light and dark, the names, labels and hints people read, and every card.
Use AI to write a plug-in
An AI assistant, such as Claude, can write a plug-in for you if you give it the rules. Copy this into the assistant, and change the first line to what you want:
Write a Starboard plug-in that [say what it should do].
Rules:
- One file, starboard-plugin.json, with manifest_version 1, id, name, version, description, author, licence,
homepage, support_url, starboard_api ">=1.0 <2.0" and permissions.
- Styles: permission "appearance:styles"; each style has id, name, description, radius 0 to 24,
font (hyperlegible, system, rounded, serif or mono), shadow (none, soft or strong), and light and dark sets of
bg, header, surface, surface_raised, surface_sunken, text, text_muted, border, divider, accent, accent_text,
accent_soft and focus as #rrggbb.
- Contrast, in light and dark: text on bg, header, all three surfaces and accent_soft at least 4.5:1;
text_muted and accent on bg and surfaces at least 4.5:1; accent_text on accent at least 4.5:1;
border and focus on bg and surfaces at least 3:1. Show me each ratio.
- Cards: type stat, list or status, a path, and an example answer in the right shape.
- No CSS, HTML, scripts, fonts or pictures. Only the fields in this list.
Then test what it writes. Read Test your plug-in. Fix each error, or paste the tester's issues back into the assistant and ask it to fix them. Check the result yourself before you share it: the tester checks the rules, not whether you like the colours.
Share it
Put the folder somewhere people can reach, such as a Git repository, and give them the https address of its
starboard-plugin.json. To add a one-step installer like the Styles plug-in has, copy its install.py.
Find out more
This page on GitHub, where the help is written.