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.

What is a plugin?

A plugin is a small program that listens to events in a Discord server and reacts to them.

• Someone joins your server → your plugin sends a welcome message.
• Someone types /leaderboard → your plugin replies with the top 10 users.
• Someone reacts to a message → your plugin counts the vote and updates the tally.

You write Python. You import the SDK. You decorate a function with @plugin.on_event("member_join") and write what should happen. The platform handles the rest.

What the platform does for you

• Connects to Discord. You never deal with WebSocket gateways, sharding, intents, or rate limits. The platform delivers events to your handlers, and one ctx.discord.send_message(…) call replies.
• Hosts your code. No servers to rent, no Docker to manage, no deploys at 2 AM. Push your code — the platform runs it in an isolated sandbox.
• Talks to the outside world. Call external APIs with ctx.http, hold live connections open with ctx.ws and let the platform inject API keys from encrypted secrets so your code never touches them. See Outbound HTTP.
• Takes payments. Set a price or ship it free. Customers pay through Stripe and you keep 70–85% of revenue (tier depends on your last 30 days of volume), paid out to your bank automatically after a hold period. See Selling your plugin.
• Scales for you. One install or one million — the platform handles concurrency, retries, quotas.

What you do

Write the logic that turns Discord events into actions. That's it. The flow looks like this:

   ┌─────────────────┐     ┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
   │  Discord event  │────▶│   YourBot       │────▶│  Your plugin's   │────▶│   YourBot       │
   │  (msg, /cmd…)   │     │   gateway        │     │   handler        │     │   sends to       │
   │                 │     │                  │     │                  │     │   Discord        │
   └─────────────────┘     └──────────────────┘     └──────────────────┘     └──────────────────┘
                                                              ▲
                                                              │
                                                    you write this part

How a plugin is different from a "Discord bot framework"

Concern	Plugin (this platform)	Self-hosted bot (discord.py, etc.)
Connect to Discord	Platform does it	You do it
Server to host code	Platform provides	You rent / manage
Payments / Stripe	Platform handles	You build it yourself
Per-customer install	One-click for customer	You walk each customer through OAuth
Scaling / quotas / retries	Platform handles	You handle it
Reviews / discoverability	Built-in marketplace	You market your bot yourself
Discord API surface	Capability-gated (declare what you need)	Full access (your responsibility)

Where you'll spend your time

1. Wiring events to handlers. Decorators like @plugin.on_event("message_create") or @plugin.on_slash_command("hello").
2. Storing state. Per-server settings, counters and leaderboards live in ctx.kv (key-value, every plugin has it) or ctx.sql (full SQL, a capability you request that is granted after staff review). Either way there is no database to manage.
3. (Optional) A settings page. Drop in a JSON manifest and customers get a dashboard page they can configure your plugin from. No frontend code required.

You can build and submit your first plugin in an afternoon. New developers' first versions go through a short staff review before they appear in the marketplace; established developers publish instantly. Click "Getting started" above when you're ready to write code. Prefer not to start from a blank file? The Plugin Builder writes a working first draft from a description, and the yourbot CLI runs it locally before you upload anything.

Good to know before you build

Find it fast

Jump straight to the section that answers your question. The filter box above only searches the tab you are on.

I want to…	Go to
React when someone joins, posts or clicks	Build: Events
Add a slash command	Build: Slash commands
Read the text of messages	events:message_content
Store per-server settings or counters	Storage & I/O: Key-value store
Keep an API key without hardcoding it	Storage & I/O: Encrypted secrets
Run real SQL queries	Storage & I/O: Sandboxed SQL
Call an external API	Storage & I/O: Outbound HTTP
Hold a live connection to a game server	Storage & I/O: WebSockets
Do something on a schedule	Build: Cron schedules
Give admins a settings page	Dashboards: Manifest mode
Test my plugin before uploading	Getting started: The yourbot CLI
See what my plugin is allowed to touch	Reference: Capability catalog
Check every size and rate limit	Reference: Limits and quotas
Charge money for my plugin	Production: Selling your plugin
Publish and get reviewed	Production: Publish & review