Bots
Members of a group that are run by a program on a machine an admin controls. For group admins.
The bot runs on your admin's machine; no developer and no Pollis server holds its keys.
Running the machine: Self-hosting a bot. Posting alerts and how the runtime works: Bots for developers.
Four words, four different things
These words are kept apart in the apps, in these docs and in the code.
| Word | What it is |
|---|---|
| App | The code that decides what a bot does. It runs only inside the runtime. |
| Installation | One App set up in one group, with the permissions (grants) an admin chose. |
| Bot | The installation's user: the member everyone in the group sees. |
| Runtime | Pollis's pollis-bot program. The only thing that ever holds a
bot's keys or talks to the network for it. |
A bot is not the machine it runs on, and not the code it runs. Machines (hosts) can be added and removed while the bot stays the same member. A bot does what its App says, and an admin approves the exact App it runs. The alerts App, for example, posts the alerts it receives on its webhook into a channel.
What a bot is, and what it can read
- It belongs to one group only, for its whole life. Any admin of the group can add it, change its hosts and delete it.
- It runs on a machine an admin controls, called a host. A bot can have several hosts, so it keeps running when one machine goes down.
- It is not in user search. Nobody can send it a direct message, and it cannot send one. It can never be an admin or the owner of the group, and it cannot join other groups.
- It can read every message sent in the group's channels after it joined, like a person who joined at that moment. It cannot read earlier messages, your direct messages, or other groups.
- Whoever controls a host machine can read what the bot reads. Run a bot only on a machine you trust with that.
The Bots page is where admins manage them. On desktop, open the group, then choose Bots. On mobile, open the group's settings, then Bots. Only the group's admins see it.
Add a bot
- On the Bots page, choose Add a bot. The page shows the command to run on the machine.
- On the machine, install
pollis-bot(how) and run:pollis-bot pairIt prints an eight-character pairing code and the time it expires, ten minutes later. - On the Add a bot page, type a bot name (members see it on the bot's messages) and the code. The code is never filled in for you: typing it is how you confirm you are adding the machine in front of you.
- Choose Add bot. The bot joins the group and
pollis-bot pairfinishes. The machine then starts it withpollis-bot run.
If the page says the code doesn't match, read it again from the machine and retype it. If it says the
code has expired, run pollis-bot pair again for a new one.
Add a host
A second host keeps the bot running when one machine is down. Each host holds the bot's keys.
- Open the bot from the Bots page and choose Add a host. The page
shows the command for the new machine, with the bot's id filled in:
pollis-bot add-host --bot <bot id> - Run it on the new machine. It prints a pairing code.
- Type the code on the Add a host page and choose Add host.
One of the bot's running hosts checks your approval and hands the new machine the bot's keys, so at least one existing host must be running. When a bot has several hosts, all of them see every message, and for each alert exactly one of them posts.
Revoke a host, delete a bot
Revoke a host when the machine is retired, lost or no longer trusted: open the bot, choose Revoke next to the host, and confirm. That machine stops running the bot and cannot read the group's new messages. The bot's other hosts keep it running.
Delete a bot: open the bot, choose Delete bot, and confirm. It leaves the group and stops running on every host. This cannot be undone. Deleting a group deletes its bots too.
A bot's keys exist only on its hosts. Pollis keeps no copy and has no recovery for them, so that nothing but the bot's own machines can ever act as the bot. If every host is gone, the bot cannot be recovered: delete it and add a new one. The Bots page warns you before you revoke a last host. Give an important bot a second host.
Approving an App
A bot that runs an App runs exactly the App an admin approved, with exactly the permissions the admin chose. Every App has an App hash, a fingerprint of its code and its manifest together; change one byte and the hash changes.
- Whoever runs the bot's machine points the bot at an App, from a file on that machine or an
https://address. The bot's page then shows Waiting for your approval with the App's name, version, App hash and where it comes from. - Read what it can do, in plain language: which channels it reads and how far back, what it can do, and which internet addresses it may reach, or Can't send data outside this group when it may reach none.
- Switch off anything you do not want (channels, history, addresses) and choose Approve. You can only take things away, never add beyond what the App asked for.
The approval is signed by your own device. Before every job the bot checks that signature, that you are still an admin, and that the App it is about to run has exactly the approved hash. If anything does not match, the App does not run and the bot's page says why. The Pollis server stores approvals but cannot make or change one.
Updates need a new approval. Anything a new version asks for beyond the last one is highlighted and stays off until you switch it on; an update that asks for nothing more is one tap, or can be set to approve itself. A development installation approves a developer's signing key instead of one version, for test groups; every member then sees a Development build mark on the bot.
Details: docs/bots/app-approval.md.
Limits and the Bot badge
- 25 bots per group. When a group has 25, the Bots page says so; delete one to add another.
- Bots per machine: set by whoever runs it, 8 by default (details).
Everywhere members see a bot (the member list, its messages, mentions) its name carries a Bot badge, with "Managed by the admins of <group>" on its profile. Apps that predate bots show a bot as an ordinary member.
This page is kept in step with
docs/bots/admin-guide.md.