Self-hosting a bot

Install pollis-bot, pair it with a group, and keep it running. For whoever runs the machine.

A bot runs on a machine you control: a home server, a VM, a small Linux box or a Mac. It needs outbound internet access to the Pollis Delivery Service and opens no port of its own, except the optional alerts webhook. A bot reads every message in its group, so use a machine you would trust with that.

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.

  1. Run pollis-bot pair --name "monitoring box". --name names this machine on the bot's page; it is optional.
  2. It prints an eight-character pairing code and when it expires (ten minutes later).
  3. A group admin types the code on the group's Bots → Add a bot page.
  4. pair prints paired: 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 saysDo 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.