overlord/plugins/PLUGINS.md

Overlord Plugins

This is the short entry point for plugin authors. The detailed docs are split by topic so server-only build extensions, WASM agent plugins, legacy native plugins, signing, and examples can evolve independently.

Quick Start

A Plugin 2.0 bundle is a zip with a root config.json, browser assets, and optional server or agent code:

<pluginId>.zip
  config.json
  <pluginId>.html
  <pluginId>.css
  <pluginId>.js              optional when src/ui.ts exists
  <pluginId>.wasm            optional agent-side WASM module
  server.js                  optional server-side runtime
  src/                       optional TypeScript source

Upload the zip from the Plugins page, or place it under Overlord-Server/plugins.

Read The Focused Docs

Topic	Read this
Bundle layout, config.json, TypeScript UI/server entries	docs/bundle-format.md
Server-only plugins, plugin data, RPC/SSE, build hooks, build settings/buttons	docs/server-side-plugins.md
WASM Plugin 2.0 agent modules and permissioned file bridges	docs/wasm-plugins.md
Install/upload flow, Plugin Manager behavior, auto-load rules	docs/install-and-manage.md
Sample plugin directory guide	docs/samples.md
Legacy native plugins: OS APIs, native ABI, build scripts, Linux static-agent shim	docs/legacy-native-plugins.md
Plugin signing and trusted keys	docs/signing.md

Runtime Choices

Use runtime: "server" for server-side extensions. These can add server UI, store files, expose RPCs, subscribe to plugin events, and hook the build pipeline. Server-only plugins are shown as server extensions in the Plugin Manager, are not sent to clients, and do not use auto-load.

Use runtime: "wasm" for Plugin 2.0 agent code. WASM plugins are sandboxed on the agent and access host features only through declared needs and Overlord bridge APIs.

Use legacy native plugins when you need direct OS APIs, native libraries, platform-specific behavior, or other privileged agent-side functionality that the WASM sandbox does not expose. Native plugins run with the agent's privileges and require one binary per OS/architecture.

Current Samples

Directory	Purpose
sample-build-hooks	Server-only build plugin with its own Build page button and artifact replacement example.
sample-ts-fullstack	TypeScript UI plus TypeScript server runtime.
sample-wasm	C/WASI Plugin 2.0 WASM example.
sample-wasm-hostinfo	TinyGo WASM HostInfo example.
sample-wasm-platform-note	Rust WASM platform-aware example.
sample-c, sample-cpp, sample-go, sample-rust	Legacy native v1 examples.

Start with docs/server-side-plugins.md if you are building uploaders, custom build buttons, artifact post-processing, or internal release hooks.