agentic-govbot/MASTODON_SETUP.md

Mastodon Setup Guide

This guide walks through setting up Govbot on a Mastodon instance.

Prerequisites

• A Mastodon instance (existing or test)
• Admin access to the instance (for creating bot account and getting credentials)
• Python 3.11+ installed
• Ollama (for local models) or API keys for cloud models

Step 1: Create Bot Account

On Your Mastodon Instance

1. Create a new account for the bot:

   • Go to your Mastodon instance
   • Sign up for a new account (e.g., govbot@yourinstance.social)
   • Verify the email address
   • Complete the profile (add avatar, bio explaining it's a governance bot)

2. Note the bot's username (you'll need this for configuration)

Step 2: Register Application

Get OAuth Credentials

1. Navigate to Settings while logged in as the bot account

2. Go to: Settings → Development → New Application

3. Configure the application:

   • Application name: Govbot
   • Application website: Your instance URL or governance documentation
   • Redirect URI: urn:ietf:wg:oauth:2.0:oob (for command-line auth)

4. Scopes needed:

   • read - Read account info and notifications
   • read:statuses - Read statuses
   • write - Post statuses
   • write:statuses - Create statuses
   • admin:read - Read admin data (if bot will have admin powers)
   • admin:write - Perform admin actions (if bot will manage instance)

5. Click "Submit"

6. Save credentials:

   • Client key (client_id)
   • Client secret (client_secret)
   • Access token (you may need to generate this)

Generate Access Token

If the application page doesn't show an access token:

# Run this Python script to generate an access token
from mastodon import Mastodon

Mastodon.create_app(
    'Govbot',
    api_base_url='https://your-instance.social',
    to_file='govbot_clientcred.secret'
)

mastodon = Mastodon(
    client_id='govbot_clientcred.secret',
    api_base_url='https://your-instance.social'
)

# Log in (will prompt for username and password)
mastodon.log_in(
    'your_bot@email.com',
    'your_bot_password',
    to_file='govbot_usercred.secret'
)

# The access token is now in govbot_usercred.secret
with open('govbot_usercred.secret') as f:
    access_token = f.read().strip()
    print(f"Access token: {access_token}")

Step 3: Configure Govbot

Update Configuration File

1. Copy the example config:

   cp config/config.example.yaml config/config.yaml
   

2. Edit config/config.yaml:

   platform:
     type: mastodon
   
     mastodon:
       instance_url: https://your-instance.social
       client_id: YOUR_CLIENT_ID_HERE
       client_secret: YOUR_CLIENT_SECRET_HERE
       access_token: YOUR_ACCESS_TOKEN_HERE
       bot_username: govbot  # Your bot's username
   
   ai:
     # For local models:
     default_model: llama3.2
   
     # For cloud models:
     # default_model: gpt-4
     # (Make sure to configure llm CLI with: llm keys set openai)
   
   governance:
     constitution_path: constitution.md
     db_path: govbot.db
     default_veto_threshold: 0.67
     enable_auto_execution: true
     require_confirmation_for:
       - admin_action
       - moderation
   
   debug: false
   log_level: INFO
   

3. Test LLM configuration:

   # Test that llm works
   llm "Hello, test message"
   
   # If using local models, verify Ollama is running
   ollama list
   

Step 4: Initialize Database

# Create the database
python -c "from src.govbot.db.models import init_db; init_db('govbot.db'); print('Database initialized!')"

Step 5: Test with CLI

Before connecting to Mastodon, test the bot logic:

# Run the CLI
python -m src.govbot

# Try these commands:
query What are the rules for proposals?
propose We should have weekly community meetings
processes
exit

Step 6: Run the Bot

# Start the bot
python -m src.govbot.bot

# You should see:
# INFO - Connecting to Mastodon instance: https://your-instance.social
# INFO - Connected as @govbot (ID: ...)
# INFO - Started listening for messages
# INFO - Bot is running. Press Ctrl+C to stop.

Step 7: Test on Mastodon

Basic Test

1. From another account on your instance, post:

   @govbot help
   

2. The bot should respond with information about how to use it

Create a Proposal

@govbot I propose we add a weekly community meeting on Fridays

The bot should:

• Acknowledge the proposal
• Cite constitutional authority
• Explain voting period and threshold
• Provide instructions for voting

Vote on Proposal

Reply to the proposal thread:

@govbot agree

Check Status

@govbot status 1

Granting Admin Powers (Optional)

If you want the bot to perform instance administration:

1. Grant Moderator/Admin Role

In Mastodon admin interface:

• Go to Moderation → Accounts
• Find the bot account
• Assign Moderator or Admin role

2. Update Constitution

Make sure your constitution specifies when and how admin powers can be used:

## Admin Powers

The bot may perform administrative actions only when:
1. Authorized by constitutional amendment process
2. Approved by supermajority vote
3. Within scope of delegated authority

Admin actions include:
- Updating instance rules
- Moderating content
- Managing user accounts
- Changing instance settings

3. Test Admin Skills

@govbot What admin actions can you perform?

Troubleshooting

Bot Not Receiving Mentions

Check:

• Bot account access token is valid
• read scope is enabled
• Bot is following the mentioning account (or has appropriate visibility settings)
• Bot is actually running (check logs)

Test manually:

from mastodon import Mastodon

client = Mastodon(
    access_token='YOUR_TOKEN',
    api_base_url='https://your-instance.social'
)

# Check notifications
notifications = client.notifications()
print(notifications)

Bot Can't Post

Check:

• write:statuses scope is enabled
• Access token is valid
• Instance isn't rate limiting the bot
• Bot account isn't silenced/suspended

Connection Errors

Check:

• Instance URL is correct (include https://)
• Instance is accessible from bot's network
• Firewall isn't blocking connection
• Instance isn't experiencing downtime

LLM Errors

For local models:

# Check Ollama is running
ollama list
ollama ps

# Test the model
llm -m llama3.2 "test"

For cloud models:

# Check API keys
llm keys list

# Test the model
llm -m gpt-4 "test"

Database Errors

Reset database:

# Backup first!
cp govbot.db govbot.db.backup

# Delete and reinitialize
rm govbot.db
python -c "from src.govbot.db.models import init_db; init_db('govbot.db')"

Security Considerations

📖 See SECURITY.md for the complete security guide.

Credentials

• Never commit config/config.yaml to version control (it's in .gitignore)
• Never commit *_clientcred.secret or *_usercred.secret files (also gitignored)
• Store credentials securely
• Use environment variables for production:

  export GOVBOT_PLATFORM__MASTODON__ACCESS_TOKEN="your_token"
  

• Rotate tokens periodically

Access Control

• Don't grant unnecessary scopes
• Use separate accounts for testing vs. production
• Monitor bot actions through audit log
• Set up alerts for suspicious activity

Rate Limiting

The bot respects Mastodon's rate limits. If you see rate limit errors:

• Reduce frequency of checks in scheduler
• Implement exponential backoff
• Consider caching frequently accessed data

Production Deployment

Systemd Service

Create /etc/systemd/system/govbot.service:

[Unit]
Description=Govbot Governance Bot
After=network.target

[Service]
Type=simple
User=govbot
WorkingDirectory=/home/govbot/agentic-govbot
ExecStart=/usr/bin/python3 -m src.govbot.bot
Restart=always
RestartSec=10

Environment="GOVBOT_LOG_LEVEL=INFO"

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable govbot
sudo systemctl start govbot
sudo systemctl status govbot

# View logs
sudo journalctl -u govbot -f

Docker Deployment

Create Dockerfile:

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install -e .

CMD ["python", "-m", "src.govbot.bot"]

Build and run:

docker build -t govbot .
docker run -v $(pwd)/config:/app/config -v $(pwd)/govbot.db:/app/govbot.db govbot

Monitoring

• Set up log aggregation (e.g., Loki, Elasticsearch)
• Monitor database size
• Track API usage and rate limits
• Alert on error rates
• Monitor governance activity

Next Steps

• Customize the constitution for your community
• Test governance workflows
• Gather community feedback
• Iterate on processes
• Document your instance's governance

Getting Help

• Check QUICKSTART.md for general usage
• Review PLATFORMS.md for platform details
• See README.md for architecture overview
• Open an issue on GitHub for bugs or questions

---

Important: This is governance infrastructure. Test thoroughly before deploying to a production community!