Installing Plugins

Stoa comes with a built-in CLI to install, list and remove plugins without manually editing source files.

Prerequisites

• The Go toolchain must be installed — if you're building Stoa from source, it's already present.
• Run the commands from the Stoa source directory (where go.mod lives).
• You need a built stoa binary first. If you haven't built it yet:

  make build   # produces bin/stoa

Install a Plugin

stoa plugin install <name-or-package>

You can use a short name for official Stoa plugins:

stoa plugin install n8n

Or a full Go import path for any community plugin:

stoa plugin install github.com/stoa-hq/stoa-plugins/n8n
stoa plugin install github.com/example/my-stoa-plugin

Or a local directory path for plugins in development — no publishing required:

# Plugin inside the Stoa source tree (same Go module)
stoa plugin install ./plugins/meinplugin

# Plugin outside the Stoa source tree (separate Go module)
stoa plugin install ../my-plugin

stoa plugin remove cleans everything up automatically.

The command:

1. Runs go get <package>@latest to fetch the plugin (remote only)
2. Adds a blank import to cmd/stoa/plugins_generated.go
3. Rebuilds the stoa binary in-place
4. Prints Done. Restart stoa to apply changes.

After the rebuild, restart Stoa:

# systemd
sudo systemctl restart stoa

# or manually
./stoa serve

List Installed Plugins

stoa plugin list

Output:

 • github.com/stoa-hq/stoa-plugins/n8n
 • github.com/example/my-stoa-plugin

Remove a Plugin

stoa plugin remove <name-or-package>

stoa plugin remove n8n
# or
stoa plugin remove github.com/stoa-hq/stoa-plugins/n8n

The command removes the import from plugins_generated.go, runs go mod tidy on go.plugins.mod to clean up unused dependencies, and rebuilds the binary.

Official Plugins

Short Name	Package	Description
n8n	github.com/stoa-hq/stoa-plugins/n8n	n8n workflow automation via webhooks

How It Works

The install command manages two gitignored files:

cmd/stoa/plugins_generated.go — blank imports that activate each plugin:

// Code generated by "stoa plugin install". DO NOT EDIT.
package main

import (
    _ "github.com/stoa-hq/stoa-plugins/n8n"
)

The blank import (_) triggers the plugin's init() function, which calls sdk.Register(New()). On startup, Stoa reads all registered plugins and initialises them automatically — no manual wiring in app.go needed.

go.plugins.mod / go.plugins.sum — an isolated modfile for plugin dependencies. go.mod and go.sum are never modified, so plugin installations are never accidentally committed.

go.mod           ✓ committed — untouched by plugin install
go.plugins.mod   ✗ gitignored — user-specific plugin deps
go.plugins.sum   ✗ gitignored — checksums for plugin deps
plugins_generated.go ✗ gitignored — generated blank imports

go.plugins.mod is created automatically on first install as a copy of go.mod. If go.mod changes significantly (e.g. after a Stoa update), delete go.plugins.mod and reinstall your plugins to regenerate it.

Existing tracked file

If plugins_generated.go was committed to git before upgrading, remove it from tracking:

git rm --cached cmd/stoa/plugins_generated.go
git commit -m "chore: untrack plugins_generated.go"

Plugin Configuration

Most plugins read their settings from config.yaml under the plugins key:

plugins:
  n8n:
    webhook_base_url: "http://n8n:5678/webhook/stoa"
    secret: "change-me"
    timeout_seconds: 10

Refer to the individual plugin documentation for all available options.

Next Steps

• Creating a Plugin — build your own plugin
• n8n Workflows — configure the n8n integration