mauriceboe
0a5c8be83d
- Wiki pages (sync to the GitHub wiki on push to main): Plugins overview + trust model, Plugin Development (SDK, definePlugin, ctx, routes/jobs, the client bridge, testing with the mock host), Plugin Permissions reference, and Publishing (registry PR + CI gates + provenance). Linked from the sidebar. - Reference plugin plugin-sdk/examples/trip-countdown: a complete, minimal- permission widget (reads trip data through ctx, renders in the sandboxed iframe via the bridge, filled-in README). Validated in the SDK test suite so it passes the exact gate authors face.
3.1 KiB
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.
Enabling plugins
The plugin runtime is off by default. To turn it on, set the environment variable on your instance and restart:
environment:
- TREK_PLUGINS_ENABLED=true
When it's off, the Admin → Plugins tab shows a "disabled by server configuration" banner and nothing runs.
The isolation model — what a plugin can and can't do
Each active plugin runs as a separate OS process with a deliberately empty environment:
- It has no access to
JWT_SECRET, the database connection, or any TREK secret — those are simply not in its process. - It cannot open
trek.db. 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.
- If a plugin crashes, hangs, or runs out of memory, only its process dies — TREK keeps running and restarts or disables it.
This means the permission list you approve at activation is a real boundary, not a label. See Plugin Permissions for exactly what each permission grants.
Installing a plugin
Two ways, both from Admin → Plugins:
- From the registry. Click Browse plugins, pick one, and Install. TREK downloads the pinned version from GitHub, verifies its SHA-256 against the registry, safely unpacks it, and registers it — inactive. Nothing runs yet.
- From disk. Drop a plugin directory into the
/pluginsvolume and click Rescan (or restart). TREK discovers it and registers it inactive.
Activating a plugin
Activation is a separate, deliberate step. You review the plugin's requested permissions and outbound hosts on a consent screen, then click Activate — which grants those permissions and spawns the isolated process. A page plugin then appears in the top navigation; a widget appears on the dashboard.
Managing plugins
- Disable stops the process immediately; the plugin keeps its data.
- Uninstall removes the code and lets you keep or delete the plugin's data.
- View errors shows the plugin's own error log (crashes, failed requests).
Building your own
See Plugin Development and the trek-plugin-sdk package.
Kill switch
Set TREK_PLUGINS_ENABLED=false to disable the entire subsystem instantly —
installed plugins stay on disk, deactivated and harmless.