stoat_role_bot/VERIFY.md

Verifying the Stoat Role Bot (container running but bot shows offline)

1. Check container logs

On the NAS (SSH or container log viewer in UGOS):

# If using Docker
docker logs stoat-role-bot

# If using Podman
podman logs stoat-role-bot

# Follow logs in real time
docker logs -f stoat-role-bot

What to look for:

Log line	Meaning
Connecting to Stoat/Revolt API...	Bot started, attempting login
Logged in as <name> — bot is online	Success – gateway connected; if Stoat still shows offline, it may be a cache/UI delay
Login failed: ...	Wrong token, revoked token, or API unreachable
Unhandled rejection: / Uncaught exception:	Runtime error (e.g. network, API change) – the message will say what failed
No "Logged in" after "Connecting..."	Connection to API or WebSocket failed (network/firewall)
Skipping key voice during hydration!	Ignore. From revolt.js while loading server data; harmless.

---

2. Verify environment variables

Ensure the container has the token:

docker exec stoat-role-bot env | grep -E 'STOAT_BOT_TOKEN|REVOLT_BOT_TOKEN|PREFIX'

• You should see STOAT_BOT_TOKEN=... or REVOLT_BOT_TOKEN=... with a non-empty value.
• If they’re empty or missing, set them in the container creation (env vars or .env file) and recreate the container.

---

3. Test outbound connectivity (from NAS)

The bot only needs outbound HTTPS and WebSocket. From the NAS (SSH) or from another container on the same host:

# Can the NAS reach the Revolt/Stoat API?
curl -s -o /dev/null -w "%{http_code}" https://api.revolt.chat
# Expect 200 or 401 (API is up)

# Optional: WebSocket (may not be available in curl)
curl -sI "https://api.revolt.chat"

If these fail, the NAS or its Docker network may be blocking outbound traffic (firewall or proxy).

---

4. Token and bot status

• Token: Create a new bot token in your Stoat server (Server → Bots → your bot → regenerate/copy token). Update the container env with the new token and restart.
• Bot role: The bot’s role must be above any role it assigns. Move it up in the server’s role list.
• Invite: The bot must still be in the server. If you removed it, re-invite it with the correct permissions (e.g. Assign Roles).

---

5. Test in a channel (once logs say "online")

In a Stoat channel the bot can see:

1. Send: !roles
   • Expected: Bot replies with the list of self-assignable roles (or a message that none are configured).
2. If that works, try: !role add <RoleName> (use a role from the list).

If the bot replies, it’s working; “offline” in the UI may be a display delay.

---

6. Restart the container

After changing env vars or fixing config:

docker restart stoat-role-bot
# then
docker logs -f stoat-role-bot

---

Quick checklist

• Logs show Connecting to Stoat/Revolt API...
• Logs show Logged in as … — bot is online (no login error)
• STOAT_BOT_TOKEN (or REVOLT_BOT_TOKEN) is set in the container
• NAS can reach https://api.revolt.chat
• Bot role is above roles it should assign; bot is still in the server
• In a channel, !roles gets a reply from the bot

If logs show a specific error (e.g. InvalidSession, NotAuthenticated, or a network error), that message is the next place to look (token vs network vs permissions).