Self-hosting a bot
Install pollis-bot, pair it with a group, and keep it running. For whoever runs the machine.
For group admins: Bots. The full reference is
pollis-bot --help.
Install
pollis-bot is built from the Pollis repository with Rust (stable, from
rustup.rs).
git clone https://github.com/pollis-app/pollis.git
cd pollis
cargo build --release -p pollis-bot
install -m 755 target/release/pollis-bot ~/.local/bin/
Tell it which Delivery Service to use (R2_S3_ENDPOINT and R2_PUBLIC_URL must be
set but can be empty), then check it runs:
export POLLIS_DELIVERY_URL=https://api.pollis.com
export R2_S3_ENDPOINT= R2_PUBLIC_URL=
pollis-bot --version
Pair
Pairing creates the bot and makes this machine its first host.
- Run
pollis-bot pair --name "monitoring box".--namenames this machine on the bot's page; it is optional. - It prints an eight-character pairing code and when it expires (ten minutes later).
- A group admin types the code on the group's Bots → Add a bot page.
pairprintspaired: bot … in group …and exits.
Run pair as the same user, on the same machine, that will run the service: the bot's keys
are stored for that user.
Run
pollis-bot run # every bot on this machine, until stopped
pollis-bot run --webhook # also listen for alerts on 127.0.0.1:8787
pollis-bot status # what each bot is doing
run catches up on anything it missed, then waits for events. Nothing is lost while it is
stopped, and a host does not have to stay up: pollis-bot run --once catches up, handles
everything pending (including approving another host) and exits, for a machine that sleeps. The first time the webhook is on, it prints each installation's webhook secret once; see
the alerts webhook. To keep the webhook on, put
{ "webhook": { "bind": "127.0.0.1:8787" } } in config.json in the data
directory.
Run as a service
Run pollis-bot run under your service manager, as the user who ran pair.
Linux (systemd), on a server
/etc/systemd/system/pollis-bot.service:
[Unit]
Description=Pollis bot runtime
Wants=network-online.target
After=network-online.target
[Service]
User=pollis-bot
Environment=HOME=/var/lib/pollis-bot
Environment=POLLIS_DELIVERY_URL=https://api.pollis.com
Environment=R2_S3_ENDPOINT=
Environment=R2_PUBLIC_URL=
ExecStart=/usr/local/bin/pollis-bot --data-dir /var/lib/pollis-bot run
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
sudo useradd --system --home-dir /var/lib/pollis-bot --create-home pollis-bot
sudo install -m 755 target/release/pollis-bot /usr/local/bin/
sudo -u pollis-bot -H env POLLIS_DELIVERY_URL=https://api.pollis.com R2_S3_ENDPOINT= R2_PUBLIC_URL= \
pollis-bot --data-dir /var/lib/pollis-bot pair --name "$(hostname)"
sudo systemctl daemon-reload
sudo systemctl enable --now pollis-bot
journalctl -u pollis-bot -f
On a desktop Linux machine where you paired from your own session, use a user unit instead
(~/.config/systemd/user/pollis-bot.service, without User= and
HOME=, WantedBy=default.target) and
systemctl --user enable --now pollis-bot.
macOS (launchd)
A LaunchAgent for the user who paired, in ~/Library/LaunchAgents/com.pollis.bot.plist. It
starts when that user logs in, because the keychain it uses is unlocked at login.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>com.pollis.bot</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/pollis-bot</string>
<string>run</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>POLLIS_DELIVERY_URL</key><string>https://api.pollis.com</string>
<key>R2_S3_ENDPOINT</key><string></string>
<key>R2_PUBLIC_URL</key><string></string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardErrorPath</key><string>/tmp/pollis-bot.log</string>
</dict>
</plist>
launchctl load ~/Library/LaunchAgents/com.pollis.bot.plist
Windows
Start pollis-bot run from Task Scheduler with the trigger At log on for the
user who paired, and Restart if the task fails turned on.
How the keys are kept
A bot starts with nobody present, so it has no PIN. Each bot's keys and the key to its encrypted local store sit in the machine's keystore: the OS keychain where there is one, otherwise an encrypted file bound to this machine. They are never stored in plain text. This protects against someone who copies the disk or a backup to another machine. It does not protect against someone who can run programs as the same user on this machine, or who has a full image of it. Keep the machine, and the account the bot runs as, as private as the conversations the bot can read.
Several bots on one machine
One runtime can host several bots, in one group or several. Each is a separate
installation with its own keys, keystore entry and encrypted store; nothing is shared
between them. Run pollis-bot pair once per bot; run runs them all.
The runtime refuses to host more than max_installations, 8 by default, so
a machine is not overloaded by accident. Raise it in config.json
({ "max_installations": 12 }) or for one run with
run --max-installations N.
Add this machine as another host, or upgrade
To add this machine to an existing bot, copy the command from the bot's Add a host
page (pollis-bot add-host --bot <bot id>), run it here, and have the admin type the
code. One of the bot's running hosts hands this machine the bot's keys. Then start it with
pollis-bot run. To move a bot to a new machine, add the new one, check it runs, then revoke
the old one; copying the data directory to another machine does not work, by design.
To upgrade, stop the service, rebuild and replace the binary, and start it again. Installations, keys and settings stay; the first job catches up on what was sent meanwhile.
Files, logs and status
The data directory is --data-dir, else POLLIS_BOT_DATA_DIR, else
~/.local/share/pollis-bot (Linux), ~/Library/Application Support/com.pollis.bot
(macOS) or %APPDATA%\pollis-bot (Windows). It holds config.json,
installations/<id>/installation.json, each installation's encrypted store in
stores/<device id>/ (including how far its job loop has read each channel),
and status.json. The bot's keys are in the keystore: the OS keychain, or where there is none,
keystore.pks in this same directory, encrypted and bound to the machine.
pollis-bot forget --installation <id> removes an installation's record, store
and keys together.
pollis-bot logs to standard error, one line per event. Every failure reads
FAILED: <what happened>. Fix: <one thing to do>.
pollis-bot status shows each installation as starting,
catching up, connected or job failed (with the error and the
fix).
| The message says | Do this |
|---|---|
the code expired before an admin typed it |
Run pair or add-host again; type the new code
within ten minutes. |
this host already runs bot … |
Run add-host on a different machine. |
configured for at most N installations |
Raise max_installations, or use another machine. |
no installations on this host |
Run pollis-bot pair. |
opening installation … |
The host may have been revoked or the bot deleted. If so, run
pollis-bot forget --installation <id>, then pair again if the bot
should stay. |
unattended_refused: no bot installation for this account on this machine |
Run as the user who paired, or pair again. |
binding the webhook listener to … |
Pick a free address in webhook.bind or
run --webhook ADDR. |
job failed while catching up / claiming the trigger /
posting |
Check the machine reaches the Delivery Service. It retries without posting twice. |
job failed while saving progress |
Check the data directory is writable and has space. |
webhook call with a wrong secret or signature |
Give the sender the current secret (rotate-secret makes a new
one). |
Every message and its fix:
docs/bots/self-hosting.md, which this page is kept in step
with.