SwarmBot

Forgecode Swarm Bot - WhatsApp to Forgejo agent orchestration.

Architecture

You (WhatsApp) --> Evolution API (webhook) --> Webhook Server
                                                       |
                                               Parse instruction
                                                       |
                                       Create issue on Forgejo (local or remote)
                                                       |
                                       Agent executes the task
                                                       |
                                       Notify result on WhatsApp

Components

Component	Path	Description
Bot	bot/forgejo_wa_bot.py	Polls Forgejo issues and sends WhatsApp notifications
Agent	agent/forgejo_agent.py	Processes da-fare issues, executes tasks, closes them
Webhook	webhook/forgejo_webhook.py	Receives WhatsApp messages and creates Forgejo issues
Evolution API	evolution-api/	Docker-compose for WhatsApp API bridge
Nginx	nginx/forgejo.conf	Reverse proxy config for Forgejo
Forgejo	forgejo/app.ini	Forgejo application config
Systemd	systemd/	Service and timer units
Utils	utils/set-poll-interval	Utility to change agent polling interval

Issue Workflow Labels

Label	Color	Meaning
da-fare	Red	Task queued, agent will pick it up
in-corso	Yellow	Agent is executing the task
completata	Green	Task completed, issue will be closed

WhatsApp Commands

Command	Effect
help	Show available machines
restart nginx	Create issue on local server
@server2 restart nginx	Create issue on remote server
cmd: echo hello > /tmp/test.txt	Explicit shell command

Installation

1. Forgejo

# Download and install Forgejo
curl -sL -o /usr/local/bin/forgejo https://codeberg.org/forgejo/forgejo/releases/latest/download/forgejo-*-linux-amd64
chmod +x /usr/local/bin/forgejo

# Create user and directories
useradd -r -m -d /var/lib/forgejo -s /bin/bash git
mkdir -p /etc/forgejo /var/lib/forgejo /var/log/forgejo
chown -R git:git /etc/forgejo /var/lib/forgejo /var/log/forgejo

# Copy config and start
cp forgejo/app.ini /etc/forgejo/
chown -R git:git /etc/forgejo
cp systemd/forgejo.service /etc/systemd/system/
systemctl daemon-reload && systemctl enable --now forgejo

2. Nginx + SSL

cp nginx/forgejo.conf /etc/nginx/conf.d/
dnf install -y certbot python3-certbot-nginx
certbot --nginx -d your-domain.com
systemctl enable --now nginx

3. Evolution API

cp -r evolution-api/ /opt/evolution-api/
cd /opt/evolution-api
cp .env.example .env
# Edit .env with your secrets
docker compose up -d

4. SwarmBot

# Copy scripts
cp -r bot/ /opt/forgejo-whatsapp-bot/
cp agent/forgejo_agent.py /opt/forgejo-whatsapp-bot/
cp webhook/forgejo_webhook.py /opt/forgejo-whatsapp-bot/
cp webhook/machines.yaml.example /opt/forgejo-whatsapp-bot/machines.yaml

# Configure
cd /opt/forgejo-whatsapp-bot
cp bot/.env.example .env
# Edit .env and machines.yaml with your secrets

# Install systemd services
cp systemd/forgejo-wa-bot.service systemd/forgejo-wa-bot.timer /etc/systemd/system/
cp systemd/forgejo-agent.service systemd/forgejo-agent.timer /etc/systemd/system/
cp systemd/forgejo-webhook.service /etc/systemd/system/
cp utils/set-poll-interval /usr/local/bin/

systemctl daemon-reload
systemctl enable --now forgejo-wa-bot.timer
systemctl enable --now forgejo-agent.timer
systemctl enable --now forgejo-webhook

5. Connect WhatsApp

# Create WhatsApp instance
curl -s -X POST http://127.0.0.1:8080/instance/create \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceName":"forgejo-bot","qrcode":true,"integration":"WHATSAPP-BAILEYS","number":"YOUR_PHONE"}'

# Set webhook
curl -s -X POST http://127.0.0.1:8080/webhook/set/forgejo-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook":{"enabled":true,"url":"http://127.0.0.1:8090/webhook","byEvents":true,"events":["MESSAGES_UPSERT"]}}'

# Scan QR code or use pairing code on WhatsApp

Firewall

firewall-cmd --permanent --add-service=http
firewall-cmd --permanent --add-service=https
firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="TRUSTED_IP" service name="ssh" accept'
firewall-cmd --permanent --remove-service=ssh  # Remove open SSH
firewall-cmd --reload

Dependencies

• Rocky Linux 9 / RHEL 9
• Forgejo v14+
• Nginx
• Docker + Docker Compose
• Python 3.9+ with: requests, flask, pyyaml
• Evolution API v2.3+

Adding Remote Machines

Edit /opt/forgejo-whatsapp-bot/machines.yaml:

machines:
  local:
    forgejo_url: "https://git.infinitech.it"
    forgejo_token: "YOUR_TOKEN"
    repo: "forgejo-admin/Inhandout"
    description: "Local server"

  server2:
    forgejo_url: "https://git.other-server.it"
    forgejo_token: "REMOTE_TOKEN"
    repo: "admin/tasks"
    description: "Production server"

Then restart: systemctl restart forgejo-webhook

From WhatsApp you can now write @server2 command to delegate tasks to the remote Forgecode agent.