Plugins

Plugins

Plugins let anyone extend a self-hosted TREK instance with new features — a dashboard widget, a full page, a photo/calendar integration — without touching TREK's source code. They are developed by third parties, distributed from a public registry, and installed at the instance owner's discretion.

Important

Plugins run arbitrary code, isolated but real. Every plugin runs in its own sandboxed child process with only the permissions you approve. TREK does not maintain, audit, or take responsibility for community plugins. Grant a plugin only the access you'd trust it to have with your data, and prefer plugins marked Reviewed.

Plugin types

A plugin declares one type in its manifest, which decides where it surfaces:

Type	Where it shows	Typical use
widget	On the dashboard — in the sidebar, or (with slot: "hero") as a boarding-pass style hero overlay	At-a-glance info like flight status or weather
page	As its own entry in the top navigation	A full self-contained tool
integration	Nowhere visible — registers into TREK via hooks (e.g. a photo provider or calendar source)	Feed data into existing TREK features

Enabling plugins

The plugin system is on by default — the runtime and the Admin → Plugins tab are available out of the box. Installed plugins still have to be activated one by one, so nothing third-party runs until you turn a specific plugin on.

To switch the whole system off, set the environment variable to false and restart:

environment:
  - TREK_PLUGINS_ENABLED=false

When it's off, the Admin → Plugins tab shows a "turned off (TREK_PLUGINS_ENABLED)" banner and nothing runs. Installed plugins stay on disk, deactivated and harmless, until you turn the system back on.

The isolation model — what a plugin can and can't do

Each active plugin runs as a separate OS process, started under Node's permission model (--permission) with filesystem reads scoped to just its own code:

• It has no access to JWT_SECRET, the database connection, or any TREK secret — those are simply not reachable by its process.
• It cannot open trek.db, write files, spawn child processes, use worker threads, or load native addons. Its own data lives in a separate SQLite file it reaches only through TREK.
• It talks to TREK exclusively over an internal RPC channel, and TREK only answers the capabilities the plugin's manifest declares and you approve. An ungranted call is refused, not merely ignored.
• A page/widget's interface runs in a sealed browser frame that can't read your session cookie or touch the surrounding TREK page.
• If a plugin crashes, hangs, or runs out of memory, only its process dies — TREK keeps running and can restart or disable it.

This means the permission list you approve is a real boundary, not a label. It bounds what a plugin can touch, not its intent within a grant: a plugin you let read trips and reach a host could send those trips there. See Plugin Permissions for exactly what each permission grants.

The Admin → Plugins panel

A single panel with a segmented Installed / Discover switch at the top left, plus a toolbar:

• Search — filters the current list by name/description (and author, in Discover).
• Type filter — All / Widget / Integration / Page.
• Status filter (Installed view only) — All / Active / Off / Update available / Error.
• Sort — Name / Recently updated / Updates first.
• Rescan — re-reads the on-disk plugins directory (see Installing).

Each installed row shows an icon tile with a health dot (green = active, blue pulse = starting, red = error, amber = disabled/incompatible, faint = inactive), the name and version, a Reviewed shield if applicable, and capability chips derived from its declared permissions — "Reads your trips", "Dashboard widget", "Real-time updates", "Provides photos", outbound hosts, and so on — so a plugin's real reach is legible without opening anything.

Reviewing a plugin before install

In Discover, click any card to open its detail modal. This is where you review a plugin before it touches your instance. It fetches the plugin's live manifest (at the reviewed commit) and lays out:

• What it can access — the permission-derived capabilities in plain language.
• Connects to — the outbound hosts it declared (egress).
• Setup — configuration fields it will ask for, with scope (instance/user) and whether each is required.
• Details — version, download size, minimum TREK version, review date, plus links to the source repo and homepage.

A Reviewed badge means a TREK maintainer scanned that exact version's source for malware — not that it works well or is harmless. It is not an ongoing guarantee. Read the access list and outbound hosts, not just the description.

Installing a plugin

Two ways, both from Admin → Plugins:

1. From the registry. In Discover, open a plugin and click Install (also available directly on the card). TREK downloads the pinned version, verifies its SHA-256 against the registry (and an author signature if the plugin ships one), safely unpacks it, re-validates the manifest, and registers it — inactive. Nothing runs yet.
2. From disk. Drop a plugin directory into the plugins code directory (server/data/plugins, or your TREK_PLUGINS_DIR volume) and click Rescan (or restart). TREK discovers it and registers it inactive.

Activating a plugin

Activation is the toggle on the installed row. Flipping it on grants the permissions you already reviewed and spawns the isolated process; flipping it off stops that process immediately while keeping the plugin's data. A page plugin then appears in the top navigation; a widget appears on the dashboard. There is no separate "Activate" button or second consent screen — you reviewed the permissions before installing.

Managing a plugin

The ⋯ menu on each row:

• Restart — stop and re-spawn the process (shown only while active).
• View error log — the plugin's own crash/failed-request log.
• Source repository — opens the plugin's GitHub repo (registry installs only).
• Delete — uninstalls: removes the code and lets you keep or delete its data.

Updating a plugin

When the registry lists a newer version, an Update to vX.Y.Z pill appears on the row, and an Update all bar summarises how many are available.

Updating swaps in the new code and, by default, transparently restarts the plugin on it. But if the new version declares more permissions or new outbound hosts, TREK installs the new code and leaves the plugin off, then shows a re-consent dialog listing exactly the new permissions and hosts. The plugin only runs again once you approve — an update can never silently widen what a plugin may do. Choosing "Later" keeps the new code installed but inactive.

Building your own

Plugins are built with the plugin SDK and its trek-plugin CLI. The CLI turns a built plugin directory into a publishable artifact and the ready-to-PR registry entry, so you never hand-compute a SHA-256 or hand-write registry JSON:

Command	What it does
trek-plugin validate [dir]	Runs the manifest + layout checks locally (a subset of registry CI, which additionally verifies the release, the artifact SHA-256, and the README over the network).
trek-plugin pack [dir] [--out plugin.zip] [--json]	Builds plugin.zip in the installer's exact layout and prints its SHA-256 + byte size. Refuses native binaries; docs/ is intentionally not shipped (the store fetches the screenshot from your repo).
trek-plugin entry --repo <o/n> --tag <vX> [--zip z] [--merge entry.json] [--out f]	Emits the registry entry — commitSha, downloadUrl, sha256, size and minTrekVersion (derived from the manifest trek range) all filled in. --merge prepends the new version onto an existing entry for updates.
trek-plugin release [dir] --repo <o/n> --tag <vX>	The one-shot: pack → create the GitHub release → print the entry.

Run them via npx trek-plugin-sdk …. See Plugin Development for the SDK and manifest, and Publishing a Plugin for the registry PR flow. Any unique slug works — only registry, install and rescan are refused (they'd collide with admin API routes) — and an id stays bound to the GitHub owner who first registered it, so nobody can repoint an existing plugin. Entries may optionally carry an author signing key (authorPublicKey + a per-version signature) for offline signature verification on top of the SHA-256 pin.