mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-10-19 13:36:48 +00:00
mauriceboe
660e4b9dfc
- 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.
79 lines
3.1 KiB
Markdown
79 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
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|Plugin-Permissions]] for exactly what each
|
|
permission grants.
|
|
|
|
## Installing a plugin
|
|
|
|
Two ways, both from **Admin → Plugins**:
|
|
|
|
1. **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.
|
|
2. **From disk.** Drop a plugin directory into the `/plugins` volume 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|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.
|