ops-jrz1/docs/learner-onboarding.md

Maubot Plugin Development - Learner Onboarding

This guide walks you through setting up your development environment for building maubot plugins.

Prerequisites

1. VS Code with the Remote-SSH extension
2. SSH key pair - if you don't have one:

   ssh-keygen -t ed25519 -C "your-email@example.com"
   

3. Your public key - send this to the admin:

   cat ~/.ssh/id_ed25519.pub
   

Getting Connected

Once the admin has set up your account, you'll receive connection details.

1. Configure SSH

Add this to your SSH config file (~/.ssh/config on Mac/Linux, C:\Users\YOU\.ssh\config on Windows):

Host maubot-dev
    HostName <server-ip>
    User <your-username>
    LocalForward 29316 127.0.0.1:29316

Replace <server-ip> and <your-username> with the values provided by your admin.

2. Connect with VS Code

1. Open VS Code
2. Press F1 (or Cmd+Shift+P / Ctrl+Shift+P)
3. Type "Remote-SSH: Connect to Host"
4. Select maubot-dev
5. Wait for VS Code to connect

3. Open Your Plugin Folder

Once connected:

1. Click "Open Folder"
2. Navigate to /home/<your-username>/plugins/hello_<your-username>
3. Click "OK"

You should see your starter plugin files.

Your First Plugin

Your starter plugin responds to two commands:

• !hello - Says hello
• !ping - Responds with pong

Build and Deploy

1. Open the integrated terminal in VS Code (Ctrl+`` or View > Terminal)

2. Build your plugin:

   make build
   

   This creates a .mbp file in the dist/ folder.

3. Open the maubot admin UI:

   • In your browser, go to: http://localhost:29316
   • Log in (ask admin for credentials)

4. Upload your plugin:

   • Go to "Plugins" tab
   • Click "Upload new plugin"
   • Select your .mbp file from dist/

5. Create an instance:

   • Go to "Instances" tab
   • Click "Create instance"
   • Select your plugin and a bot user
   • Add #learners-sandbox to allowed rooms
   • Click "Create"

6. Test in Matrix:

   • Join the #learners-sandbox room
   • Type !hello - your bot should respond!

Plugin Development

File Structure

hello_yourname/
├── maubot.yaml          # Plugin manifest (name, version, etc.)
├── hello_yourname/      # Python module
│   ├── __init__.py      # Module init
│   └── bot.py           # Your bot code
├── Makefile             # Build commands
└── dist/                # Built .mbp files

Adding Commands

Edit hello_yourname/bot.py:

from maubot import Plugin, MessageEvent
from maubot.handlers import command

class Bot(Plugin):
    @command.new("hello")
    async def hello_command(self, evt: MessageEvent) -> None:
        await evt.reply("Hello!")

    # Add your new command here:
    @command.new("dice")
    async def dice_command(self, evt: MessageEvent) -> None:
        import random
        result = random.randint(1, 6)
        await evt.reply(f"🎲 You rolled a {result}!")

Development Workflow

1. Edit your code in VS Code
2. Run make build in the terminal
3. In maubot admin, go to your instance and click "Reload"
4. Test your changes in Matrix

Makefile Commands

Command	Description
make build	Build the .mbp plugin file
make check	Check Python syntax
make clean	Remove built files

Troubleshooting

"Connection refused" when opening localhost:29316

The SSH tunnel isn't working. Make sure:

• You're connected via VS Code Remote-SSH
• Your SSH config has the LocalForward line
• Try disconnecting and reconnecting

Plugin doesn't appear in maubot

• Check that make build completed without errors
• Make sure you uploaded the .mbp file from the dist/ folder
• Check the maubot logs for errors

Bot doesn't respond to commands

• Make sure the bot is in the room (check room members)
• Check that the room is in "allowed_rooms" in instance config
• Check maubot logs for errors
• Commands are case-sensitive: !hello not !Hello

Syntax errors

Run make check to validate Python syntax before building.

Need to see logs

In the maubot admin UI, go to "Logs" to see recent activity and errors.

Resources

• Maubot Documentation
• Maubot Plugin Examples
• Matrix Python SDK (mautrix)

Getting Help

• Ask in #learners-sandbox - other learners and admins can help
• Check the maubot logs for error messages
• Review the maubot documentation