Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

docs(extensions): document the six contribution surfaces

Juan Denisdf3524b2027a
diff --git a/ROADMAP.md b/ROADMAP.md
index 9242998b..165b1974 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -608,6 +608,7 @@ happen live, and debug failures entirely from the UI.
## Extension Platform
- [x] Runtime frontend loading — installed extensions render without rebuilding the panel
+- [x] Extensions plug into the panel's own surfaces — their work shows up in the deploy console, their data in backups and restore, their health on the doctor page, their objects in search, and they can run commands across the fleet
- [ ] Signed extension releases, with explicit install consent for unsigned or third-party code
- [ ] Remaining built-ins extracted to standalone repos (including the WordPress flagship)
- [ ] Security suite (Fail2ban, ClamAV, Lynis, auto-updates, image scanning) as installable extensions for a leaner default panel
diff --git a/docs/EXTENSIONS.md b/docs/EXTENSIONS.md
index 84d8876a..a646f09f 100644
--- a/docs/EXTENSIONS.md
+++ b/docs/EXTENSIONS.md
@@ -281,11 +281,55 @@ def list_things():
| `notify` | Notifications SDK (`notify.send(event, to, data)`). |
| `jobs` | Jobs SDK (schedule/enqueue background work). |
| `sockets` | Register a status-guarded Socket.IO namespace (`/ext/<slug>`). |
+| `store` | Per-plugin key/value storage — state without a model and a migration. |
+| `deploys` | Register a deployment kind; get the Deploy Console, live logs and retry. |
+| `backups` | Register a backup kind; get policies, retention, restore and the Protection panel. |
+| `doctor` | Register a health check; it appears on the doctor page, repair button and all. |
+| `search` | Register searchable entities; they appear in the command palette. |
+| `agents` | Run a command on a managed server (gated by `agent.command:<action>`). |
| `require_permission(slug, cap)` | Capability gate — raises `PermissionDenied` if `cap` isn't declared in `permissions`. |
| `panel_version()` | The panel's version string (for in-plugin compat checks). |
Errors follow the core convention: `return jsonify({'error': 'message'}), status`.
+### Contributing to panel surfaces
+
+Six of those surfaces work the same way: you register behaviour, the panel owns
+the UI, the persistence and the error handling. Nothing on the frontend needs to
+change for your contribution to appear.
+
+```python
+from app.plugins_sdk import store, deploys, backups, doctor, search, agents
+
+# State, without adding a model + migration to core.
+mine = store.for_plugin('serverkit-minecraft')
+mine.set('world:1:seed', 8675309)
+
+# Long-running work that someone will want to watch → the Deploy Console.
+deploys.register('minecraft.restart', restart_handler)
+deploys.start('minecraft.restart', steps=['Warn players', 'Save', 'Restart'],
+ plan={'title': 'Restarting Overworld'})
+
+# Something worth backing up → policies, schedules, retention, restore.
+backups.register('minecraft.world', resolve=resolve, execute=execute, restore=restore)
+
+# "Is my thing healthy?" → the doctor page, with a working Repair button.
+doctor.register('minecraft', check_worlds, repair=back_up_stale)
+
+# Your objects → the command palette. Scope rows to query.user yourself.
+search.register('minecraft.world', find_worlds)
+
+# The fleet. Declare agent.command:<action> in your manifest first.
+agents.for_plugin('serverkit-minecraft').run(server_id, 'systemd:restart',
+ {'unit': 'minecraft'})
+```
+
+Namespace whatever you register after your plugin (`minecraft.world`) — bare
+names belong to core and are refused. Each registry's module docstring is the
+detailed contract; the shapes they hand back are normalised and capped by the
+panel, so a malformed contribution degrades rather than breaking the surface it
+appears on.
+
### Blueprint registration & the disable guard
`entry_point` (`module:bp_var`) is imported from `app.plugins.<slug>.<module>` and