Build webhook integrations for Commands Desktop. No source access required.
External interface providers (Slack-style webhook integrations) for Commands Desktop. Works with packaged installs — no source repo needed.
Webhook Source ──> Commands Gateway ──> Interface Plugin ──> Agent
| Zero dependencies | Reference plugin uses only Node.js built-ins, no npm packages required |
| Cross-platform | Bash installer for macOS/Linux, Node.js installer for Windows |
| Form-driven UI | Declare createForm and updateForm in manifest — Desktop renders the fields |
| SHA-256 integrity | Allowlist with optional hash pins, symlink rejection, dev-only bypass |
| Copy-and-go | Clone webhook-echo, edit manifest and handler, reinstall |
| Action buttons | Define custom per-interface actions in the manifest |
| Gateway routing | Custom interfaceType sent as interface_type when creating routes |
- Node.js 18+
- Commands Desktop (DMG, installer, or dev build)
git clone https://github.com/Commands-com/interface-plugins.git
cd interface-pluginsmacOS / Linux:
./scripts/install-interface-plugins.shWindows (or any platform with Node.js):
node scripts/install-interface-plugins.mjsBoth scripts copy plugins, install npm dependencies, and generate the SHA-256 allowlist.
| Platform | Default install locations |
|---|---|
| macOS / Linux | ~/.commands-com/workspace/interface-plugins |
| Windows | %LOCALAPPDATA%\commands-com\workspace\interface-plugins |
Restart Commands Desktop.
- Open an agent and go to the Interfaces tab.
- Select Webhook Echo from the provider dropdown.
- Set Signing Secret to
demo_secretand click Add Interface. - Click Copy Webhook URL.
curl -i -X POST "<webhook_url>" \
-H "x-echo-secret: demo_secret" \
-H "content-type: application/json" \
-d '{"hello":"world"}'Expected: HTTP 200 with JSON including request metadata and a running requestCount.
cp -R ./interface-plugins/webhook-echo ./interface-plugins/my-interfaceUpdate:
manifest.json— plugin metadata,createForm,updateForm, actionsindex.js— provider hooks (handleTunnelRequest,validateCreate, etc.)
Reinstall and regenerate allowlist:
./scripts/install-interface-plugins.sh # macOS/Linux
node scripts/install-interface-plugins.mjs # Windows (or any platform)Restart Commands Desktop. Your provider appears in the Interfaces tab.
| Rule | Detail |
|---|---|
| Built-in providers | Always load (including built-in Slack) |
| External providers | Additive — cannot override built-ins |
| Reserved types | slack, internal, test are blocked for external plugins |
| Allowlist | Plugin directory names must be listed |
| Integrity | If allowlist entry includes sha256, enforced at load time |
| File checks | manifest.json and index.js must be regular files (no symlinks) |
Dev-only bypass:
COMMANDS_AGENT_DEV=1 COMMANDS_AGENT_TRUST_ALL_INTERFACE_PLUGINS=1In Desktop: Settings > Developer > Dev Mode + Trust All Plugins.
interface-plugins/webhook-echo Reference implementation (copy to create new)
scripts/install-interface-plugins.sh Bash installer (macOS/Linux)
scripts/install-interface-plugins.mjs Node.js installer (cross-platform)
scripts/generate-interface-allowlist.mjs Generate allowlist with SHA-256 pins
scripts/compute-interface-plugin-sha256.mjs Compute single plugin hash
docs/CONTRACT.md Full manifest, loader, lifecycle, hook contract
GETTING_STARTED.md End-to-end authoring and testing workflow