Build a plugin

Plugins are sandboxed Python processes. Write a handler, declare your capabilities, ship a zip and we run it in a locked-down Docker container, streaming Discord events to it over JSON-RPC.

Quick start

Five minutes to a running plugin:

Hello, plugin

This whole file is a working plugin. Drop it in a folder with a manifest.json and ship it:

from yourbot_sdk import Plugin, Context

plugin = Plugin()

@plugin.on_ready
def ready(ctx: Context):
    ctx.log("Plugin booted on server " + ctx.server_id)

@plugin.on_event("message_create")
def on_message(ctx: Context, event: dict):
    if event.get("author_bot"):
        return  # ignore other bots
    if "!ping" in event.get("content", ""):
        ctx.discord.send_message(
            channel_id=event["channel_id"],
            content="Pong!",
        )

# This is the entrypoint. Without it the plugin process exits immediately.
plugin.run()

Note: reading what people type (event["content"] on message_create / message_edit) requires the events:message_content capability. Without it those events are delivered meta-only: IDs and timestamps arrive, but content, author fields and attachments are omitted (so the author_bot check above needs the capability too). Slash commands don't need it.

Plugin file structure

A plugin is a zip with this layout:

my_plugin/
├── manifest.json            # required - id, version, capabilities, …
├── __main__.py              # required - your handler code (the entry point)
├── requirements.txt         # optional - pip deps to install in the sandbox
├── dashboard_manifest.json  # optional - declarative dashboard
└── dashboard/               # optional - iframe-mode dashboard (HTML/CSS/JS)
    └── index.html

Limits: 25 MB zipped, 100 MB uncompressed, at most 500 files and 10 MB per single file. manifest.json and __main__.py must sit at the zip root; anything malformed is rejected by the upload validator (run yourbot validate locally to see the same errors before you upload).

manifest.json

Declares who you are, what version this is, and what you're allowed to do. id, name and version are required. id must match the plugin you created in the Dev Portal; version is assigned by the platform on upload and your manifest's version is stamped to match — zip uploads and GitHub pulls alike, so you never need to bump it by hand. Minimum viable manifest:

{
  "id": "my_plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "Pongs whenever someone types !ping.",
  "capabilities_required": [
    "discord:send_message",
    "events:message_content"
  ]
}

Optional fields:

Field	Purpose
capabilities_required	Capabilities you request; server admins choose which to grant at install time. A call that needs an ungranted capability raises CapabilityError at runtime, so handle it or keep your ask minimal. Capabilities your code uses but you forgot to declare are auto-added at upload with a warning. See the capability catalog.
slash_commands	Discord slash commands the platform should register on your behalf. See Slash commands. Declaring this auto-adds interaction:respond to capabilities_required, and @plugin.on_slash_command handlers with no manifest entry are auto-merged in at upload.
proxy_domains_requested	Allow-list of hostnames you'll reach through ctx.http.* (subdomains included) and ctx.ws (exact host required, no wildcard). The upload pipeline auto-detects domains from literal "https://…" URLs in your source; this field is your final review. Non-empty values auto-add proxy:http; ctx.ws.* usage auto-adds proxy:websocket.

Listing metadata (byline, icon, tags, screenshots) is edited on your Dev Portal listing page, not in manifest.json.

Plugin lifecycle

Two hooks carry a plugin's whole lifecycle today: @plugin.on_ready for setup and your event handlers for everything else.

Decorator	Fires when
@plugin.on_ready	Running locally with yourbot dev: once per process start. In production (plugins run in pool mode): once per (worker, server), right before that server's first event reaches you. Either way it runs before your handlers, which makes it the place for per-server init like seeding KV defaults.
Event handlers	Everything else. @plugin.on_event(...), @plugin.on_slash_command(...) and friends; see the Build tab.

@plugin.on_ready
def ready(ctx: Context):
    # Runs before this server's first event - seed defaults once.
    if ctx.kv.get("welcome_channel") is None:
        ctx.kv.set("welcome_channel", "")
    ctx.log("ready on server " + ctx.server_id)

plugin.run()  # required - starts the event loop and blocks forever.

@plugin.on_install / on_enable / on_disable / on_uninstall fire as advisory signals: the platform delivers them best-effort when a worker for your plugin is live (a cold start can drop one), with a tenant-scoped ctx that keeps your approved capabilities — on_uninstall can run its ctx.sql cleanup. Treat them as optimizations, never as the only path: put required init in on_ready, and design your state so leftover keys are harmless if an uninstall signal is missed.

You must call plugin.run() at the bottom of __main__.py. Without it the process exits before the SDK connects to the runner.

The yourbot CLI

The SDK installs a yourbot command. Four subcommands cover the local loop:

Command	What it does
yourbot new <id>	Scaffold a plugin folder from a template (basic, slash, welcome, cron). yourbot init is the interactive version that asks as it goes.
yourbot dev	Run your plugin locally without Docker: it boots your handlers against a simulated runner so you can fire test events at them and watch the log output live.
yourbot validate	The same checks the upload pipeline runs: manifest shape, capability legality, disallowed imports, slash commands cross-checked against your @plugin.on_slash_command handlers, and capability auto-detection (including proxy:websocket from ctx.ws usage). Fix it locally instead of discovering it after upload.
yourbot doctor	Checks your project: SDK install and version, entry point parses, manifest and capabilities, forbidden imports, requirements.txt and tests layout. Run it when something works locally but not in review.

The local loop: yourbot new, edit __main__.py, yourbot dev to exercise handlers, yourbot validate, zip the contents, upload on the Dev Portal.