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 offer it at $0. 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.
• Gives every install a settings page. Declare a few widgets in JSON and admins get a themed dashboard page for your plugin — stat cards, charts, settings forms — without you writing a line of frontend. See Dashboards.
• Ships your updates. Publish a new version and installs pick it up automatically (owners can pin a version to opt out). No migration emails, no "please re-invite the bot". See updates and rollback.
• 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:

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 publishing from public repos usually skip the queue. 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.

The whole journey at a glance

Every plugin moves through the same five stops, and these docs are laid out in the same order — the tab bar above groups them into Understand → Build → Ship → Reference. Each stop links to the section that covers it:

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
Open a pop-up form (modal)	Build: Modal dialogs
Update a message when a button is clicked	Build: Buttons & menus
Add a cooldown or rate-limit to a command	Storage & I/O: Ephemeral state
Give admins a settings page	Dashboards: Manifest mode
Build a fully custom dashboard UI	Dashboards: Iframe mode
Test my plugin before uploading	Getting started: The yourbot CLI
Write unit tests for my handlers	Production: Testing
Handle SDK errors without crashing	Production: Error handling
Understand why module globals reset	Production: Pool mode
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
See what changed in each SDK release	Reference: SDK changelog