Building a Plugin

📖 Canonical version: read this page on the official docs site — https://www.redamon.org/docs/building-a-plugin. The GitHub wiki is a mirror.

Building a Plugin

Anyone can build a RedAmon plugin and propose it for the official catalog: you do not need write access to any repository. You work in your own fork of samugit83/redamon-plugins, open a pull request, and an administrator of that repository reviews it, merges it and releases it. Once released, the plugin appears on the Plugins page of every RedAmon, where each instance's admin decides whether to install it.

This page is the path from an idea to that release, for authors without write access. The full commands are in the plugin repository's CONTRIBUTING.md. Administrators with write access follow a different procedure (see For administrators).

• The path at a glance
• Before you start
• Step by step
• What the review checks
• Updating your plugin
• For administrators
• Reference

---

The path at a glance

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#64748b','primaryTextColor':'#ffffff','primaryBorderColor':'#475569','lineColor':'#8b949e','textColor':'#737b85','edgeLabelBackground':'#475569','clusterBkg':'transparent','clusterBorder':'#8b949e','titleColor':'#737b85'},'flowchart':{'padding':14,'nodeSpacing':36,'rankSpacing':58}}}%%
flowchart TB
    subgraph YOU["you, in your fork"]
        Y1["build the plugin folder"] --> Y2["validate and test<br/>in Docker"]
        Y2 --> Y3["open a pull request"]
    end
    subgraph ADMIN["an administrator of redamon-plugins"]
        A1["reviews, may ask<br/>for changes"] --> A2["merges"]
        A2 --> A3["tags the release and<br/>approves the signed catalog"]
    end
    Y3 -- "CI checks it, with no secrets" --> A1
    A3 --> R["every RedAmon: the plugin appears<br/>on the Plugins page, Not installed"]

Loading

Step	Who
Build, validate and test the plugin	You
Open the pull request	You
Review, request changes, merge	An administrator
Tag the release and approve the signed catalog	An administrator
Install it on an instance	That instance's admin

Why you wait for an administrator. One key signs every plugin in the catalog, and RedAmon trusts a plugin because that signature says a maintainer reviewed it. So only an administrator can merge into master, create a release tag or approve the step that signs the catalog. Opening a pull request publishes nothing, and a merge is not a release: the release is a separate step an administrator takes after it.

---

Before you start

• Read the contract. README.PLUGIN_SDK.md is everything a plugin can declare, call and show, with a complete small example in its §14. Skiller is a full real plugin; its source is skiller/.
• Know what a plugin can do. It adds things only at the platform's extension points: its own page, items in the chat's gear menu, a control on a built-in skill's row, and proposed skill text a person approves. It can never change RedAmon's code, database schema, settings or scope.
• Know where it runs. Plugin code runs in the isolated plugin runner, with no internet, no database and no API keys. It may import only the Python standard library, the SDK and its own bundled pure-Python libraries; it reaches RedAmon only through the SDK, with the permissions an admin granted.
• Propose it first (recommended). For anything bigger than a fix, open an issue in redamon-plugins describing what the plugin does, which permissions it needs and where it appears. You learn early whether it fits.
• Missing a platform feature? A new extension point, SDK call or screen primitive is a change to RedAmon itself: open an issue in RedAmon first.
• What you need: a GitHub account, git, bash and Docker. Every tool and test runs inside a pinned python:3.11-slim image.

---

Step by step

1. Fork and branch

Fork samugit83/redamon-plugins on GitHub, clone your fork, and create a branch:

git clone https://github.com/<you>/redamon-plugins.git
cd redamon-plugins
git switch -c plugin/<id>

The id is lowercase letters, digits and hyphens, starts with a letter, is at most 40 characters, is not already used and is not a reserved word such as core or admin. It never changes after the first release.

2. Create the plugin folder

<id>/
  plugin.json      the manifest: version 1.0.0, dataVersion 1, the fewest permissions that work
  engine/          __init__.py and your actions (async def)
  tests/           pytest tests against the SDK's fakes (FakeSdk, ScriptedLlm)
  README.md        what it does, what it reads, what it stores, what a person must approve
  CHANGELOG.md     a "## [1.0.0]" section
  ui/              optional: screens, described in JSON
  vendor/          optional: bundled pure-Python libraries
  listing.json     optional: the icon and docs link of its card in RedAmon

The three permissions a plugin can ask for are Read chat sessions, Use a language model and Propose agent instructions. Ask only for what you use: the admin who installs your plugin reads each one in the consent dialog.

3. Check it locally

tools/run.sh validate <id>      # manifest, screens, imports, layout, changelog, listing
tools/run_tests.sh <id>         # your tests, on the oldest platform version you support
tools/run.sh pack <id>          # the archive a release would publish

These are the checks CI runs on your pull request.

4. Try it on your own RedAmon (optional, recommended)

There is no "load a folder" mode: you install it the way production does, from a catalog you sign with a development key that your RedAmon trusts. Generate the key once, pack the plugin, write a one-plugin catalog and sign it (the commands are in the plugin repository's README, "Developing a plugin against a local RedAmon"). Then add the printed PLUGINS_EXTRA_TRUSTED_KEYS line to your RedAmon's .env, run ./redamon.sh up, and use Install from file on the Plugins page (see Plugins → Install from file). Remove the key when you are done.

5. Register it

In the same branch, add /<id>/ @samugit83 to .github/CODEOWNERS and a short block for your plugin under "The plugins" in the repository's README.md.

Touch nothing else: the catalog (catalog.json and its signature), tools/, the workflows, .platform-sdk/ and other plugins' folders belong to the administrators, and the catalog is written only by the release workflow.

6. Open the pull request

Open a pull request against master of samugit83/redamon-plugins and fill in its checklist. CI validates, tests and packs every plugin with a read-only token and no secrets. If this is your first contribution, GitHub may hold the run until an administrator starts it.

7. Wait for an administrator to review and merge

An administrator reads the code, the permissions and the README, may run the plugin, and may ask for changes: push them to the same branch and the pull request updates. Only an administrator can merge, and nothing is published until they do.

8. The release

After the merge, an administrator tags the release (<id>-v1.0.0) and approves the signed catalog. You have nothing left to do. Within about six minutes the plugin appears on the Plugins page of every RedAmon as Not installed, with its permissions, and each instance's admin decides whether to install it.

---

What the review checks

• The fewest permissions that work, each one explained in the plugin's README.
• Readable code: no obfuscation, no compiled or minified files, no code downloaded or generated at run time. Bundled libraries are pure Python, under a licence compatible with MIT, with their licence files.
• No real target data anywhere: no real hostnames, IP addresses, scan output, captured traffic or credentials in code, tests or fixtures. Use synthetic data and reserved names (example.com, 192.0.2.0/24).
• Nothing that writes chat transcripts or target data to the plugin's log, which admins read.
• A plugin that proposes skill text proposes text that holds for any target, never values from the session it learned from.
• Green checks, and a README and changelog that match what the code does.

---

Updating your plugin

A new version takes the same path: a pull request, a review, a merge, then an administrator's release.

• Raise version in plugin.json: x.y.Z for a fix, x.Y.0 for a feature, X.0.0 for a change that breaks what users or stored data rely on, and add its section to CHANGELOG.md.
• If the shape of the data your plugin stores changes, raise dataVersion and add a migration (SDK guide §8).
• A released version is never changed: a broken one is fixed by the next patch version, and an administrator can revoke a harmful one, which stops it on every RedAmon.
• A new icon or docs link needs no new version: change listing.json in a pull request, and an administrator refreshes the catalog after the merge.

You never get write access for your plugin: every folder's code owner is an administrator, and each change comes as a pull request.

---

For administrators

Administrators of redamon-plugins (write access, the right to create release tags, and the reviewer of the release environment) add their own plugins by pushing to master and releasing with a tag, and merge contributed plugins as above, then release them. Their procedures, and how they differ from this one, are in RedAmon's README.PLUGINS.md §6.6 and in the plugin repository's README ("Adding a plugin (maintainers)", "Merging a contributed plugin (maintainers)", "Releases").

---

Reference

• CONTRIBUTING.md: the procedure with every command.
• README.PLUGIN_SDK.md: the plugin author's contract.
• README.PLUGINS.md: the platform's design, end to end.
• Plugins: what an admin sees when installing, updating and removing a plugin.
• Security issues in a plugin or the platform: report them privately through GitHub Security Advisories, never in a public issue.

See also: Plugins · Skiller · Agent Skills