Skip to main content

Backend plugin SDK (backend.sdk)

note

A feature with both a browser and a Python half is now a module package: one horrible-module.json, hot enable/disable from the Marketplace. A v3 plugin keeps loading unchanged.

The frontend plugin SDK lets third parties add frontend contributions (panels, widgets, commands). The backend plugin SDK is its server-side counterpart: a Python package, backend.sdk, that lets a plugin contribute server-side capabilities — HTTP routes, agent tools, /ws channels, lifespan hooks, and dash REPL facades — the same way a built-in backend module does.

Trust model (v1)

Backend plugins are trusted and unsandboxed: their code runs in-process with full backend access (filesystem, network, the registry). v1 is for localhost use, mirroring the frontend SDK's v1 trust model. Only load plugins you trust.

Writing a plugin​

A plugin is a module that exposes a module-level PLUGIN — a BackendPlugin whose setup(host) registers capabilities via the host:

from fastapi import APIRouter
from backend.sdk import AgentTool, BackendPlugin, PluginHost, PluginManifest

router = APIRouter()

@router.get("") # mounts at /api/plugins/ping
def ping():
return {"pong": True}

class PingPlugin(BackendPlugin):
manifest = PluginManifest(id="ping", name="Ping", version="1.0.0")

def setup(self, host: PluginHost) -> None:
host.add_router(router)
host.add_agent_tool(AgentTool(
name="ping.echo",
description="Echo back the given text.",
handler=lambda args: {"echo": args.get("text", "")},
parameters={"text": {"type": "string", "description": "text to echo"}},
required=["text"],
))
host.add_ws_channel("ping", ping_channel) # async (conn, message)
host.add_dash_facade("ping", PingFacade) # → dash.ping in the REPL
host.on_startup(lambda: ...) # lifespan hooks
host.on_shutdown(lambda: ...)

PLUGIN = PingPlugin()

The runnable reference is examples/backend-plugins/ping/ — it registers one of every capability and doubles as the integration test fixture.

The host API​

PluginHost (passed to setup) is the only surface a plugin needs:

MethodRegisters
host.add_router(router, prefix=None)a FastAPI APIRouter. Default prefix /api/plugins/<id>; pass prefix (joined under /api) to override
host.add_agent_tool(AgentTool(...))a server-side agent tool — its handler runs in the backend (works with no browser). side_effect=True routes it through the agent permission gate
host.add_agent(AgentSpec(...))a specialized agent in the roster (own system prompt, tool-group scope, per-agent agent.<id>.* settings and chat sessions) — addressable from the chat widget's picker and agent.delegate. Built-in ids (main, coder, dba, researcher) cannot be shadowed. See agent chat
host.add_connector(Connector(...))an external account the user can connect from the home page, whose credential the node holds server-side. See connectors
host.add_ws_channel(name, handler)an async (conn, message) handler for a new channel on the shared /ws socket
host.add_dash_facade(name, factory)an object bound to dash.<name> in every REPL session (also shows in dash.help())
host.add_training_provider(provider)one trainable-environment source for the training module (Kaggle, HF, Gymnasium, …)
host.add_search_provider(provider)a web-search provider, joining the existing fan-out and rank fusion
host.add_music_source(source)a place songs come from (Subsonic, a NAS share, SoundCloud): search() and fetch() into the music library. Reached by music.play and every playlist import with no new tools
host.add_playlist_importer(importer)an account or file format that describes playlists (Deezer, Tidal, a new export format); the import job resolves and downloads the songs
host.add_music_listener(listener)a service told what played (scrobbling) and asked what's similar (the DJ and radio)
host.add_dataset_source(source)one place training material lives — search, splits, peek, locate. See datasets
host.add_recipe_backend(backend)one training framework: its tasks, its knobs, and the code they become. Inherits the venv-introspection safety net
host.add_eval_runner(runner)one way of executing an eval suite; results land in the same tables as every other runner's
host.on_startup(hook) / host.on_shutdown(hook)lifespan hooks (sync or async)
host.loga logger namespaced to the plugin

AgentTool carries its own JSON-schema parameters/required, a handler (sync or async, returns a JSON-able value), and gate metadata (side_effect, specifier_template).

Connector carries a kind (oauth | api-key | custom), the begin/submit/ poll/disconnect callbacks that drive its flow, a status reader, the scopes it asks for, and an optional agent guide. Name its agent tools <connector.id>.* — the orchestrator groups tools by name prefix, so a mismatch splits a connector's tools off from its blurb and guide.

How it's discovered and wired​

backend.sdk.loader.load_plugins() runs once at app import. It discovers plugins from three sources, then calls each plugin's setup(host):

  1. Bundled — packages under backend/plugins/ (ships empty; drop a package in to bundle a first-party plugin).
  2. HORRIBLE_PLUGINS_DIR — an os.pathsep-separated list of directories of local plugin packages/modules (no install needed).
  3. Entry points — pip-installed packages declaring a horrible.plugins entry point.

Everything lands in one process-global registry (backend/sdk/registry.py), which the rest of the app reads where each capability is used:

A plugin that fails to import or set up is recorded in registry.errors and skipped — one bad plugin never takes the app down.

Agent tools execute backend-side​

Plugin agent tools join the always-present _core_tools(), so the model sees them every turn. When the model calls one, _dispatch_call runs it in the backend via registry.invoke_agent_tool (after the permission gate) rather than relaying it to the browser — the same path the peer-fabric tools use. A side_effect=True tool is gated like any other; read-only tools pass straight through.

Relationship to the other SDKs​

  • Frontend plugin SDK (@horribledashboard/sdk) — UI contributions, loaded in the browser. A rich plugin may ship both halves (a backend plugin for server logic + a frontend plugin for its UI); they are independent in v1.
  • dash (the Python REPL SDK) — the scripting handle. A backend plugin can extend it (host.add_dash_facade) so the REPL can drive the plugin too.

Source map​

ConcernFile
Public contract (BackendPlugin, PluginHost, AgentTool, …)backend/sdk/
Discovery + loadbackend/sdk/loader.py
Process-global registrybackend/sdk/registry.py
App wiring (router mount, lifespan, /ws fallback)backend/app.py
Agent-tool dispatchbackend/modules/agent/orchestrator.py
dash facade attachbackend/modules/repl/sdk.py
Reference pluginexamples/backend-plugins/ping/

The AI-research seams​

Four of the methods above exist so an outside contributor can extend the research pipeline without touching its core:

  • add_dataset_source — a new place datasets come from. It appears in the browser beside the Hub and a recipe can point at it like any other.
  • add_recipe_backend — a new training framework. The important part is what it does not have to write: recipes.introspect() asks the backend for probe_classes(task) and interrogates those classes in the project venv, so a new framework inherits the whole ok | renamed | unsupported | unvalidated field resolution. A backend that wrote its own validation would be a backend whose "dropped field" report drifts from every other one's.
  • add_eval_runner — a new way to execute a suite.
  • add_search_provider — a crawled corpus joining the same rank fusion.
  • add_music_source / add_playlist_importer / add_music_listener — the music library's three contracts (backend/modules/music/providers.py). Unlike the four above, a plugin reusing a built-in id (youtube, spotify, lastfm) replaces it. examples/backend-plugins/music_folder_source is a complete source in ~80 lines.

Built-ins win id conflicts in all four, matching the connector rule. See the AI-research pipeline for how they fit together.