Docs · Notifications

Phone alerts for experiments, with ntfy or Telegram

Results, questions and the morning summary reach your phone through ntfy — a free app with no account — or Telegram. With no topic set, nothing is sent.

Set it up#

$ researchforge notify setup --topic <a-long-random-topic> --test # machine-wide, for every project
$ researchforge notify status # where alerts go now
$ researchforge notify test # send another test

Then subscribe on your phone: install ntfy from the App Store or Google Play, tap + → Subscribe to topic and enter the same topic (or open https://ntfy.sh/<topic> in a browser). The dashboard does the same in Run configs → Notifications: where alerts go, how to subscribe, New topic and Send test alert, and the machine-wide topic is editable there too.

localhost:7842
Run configs notifications: topic, how to subscribe, Send test alert, level and submission policy
Run configs → Notifications (the topic shown is a placeholder)
ntfy topics are public by design: anyone who knows the name can read them. Pick a long, random topic, or use Telegram.

Which topic wins#

  • NTFY_TOPIC in the environment, if set;
  • then the competition's own topic (researchforge kaggle settings <slug> --ntfy-topic <topic>) — useful to send one competition to a teammate;
  • then the machine-wide topic from notify setup.

There is no shared fallback topic: with none of these set, nothing is sent. Every alert, sent or not, is also logged to ~/.config/researchforge/notification_log.jsonl and shown on the dashboard's Timeline.

What each level sends#

$ researchforge kaggle settings <slug> --notify-level balanced # verbose | balanced | minimal
Alertverbosebalancedminimal
A submission candidate is ready✓✓✓
The loop needs your answer (questions, plans)✓✓✓
Something is wrong (hung round, sensor error)✓✓✓
A round beat the best so far✓✓—
A public notebook beats your score✓✓—
Two independent wins can be merged✓✓—
The morning summary✓✓—
Every result, including no change and failures✓——
New ideas reached the pool✓——

balanced is the default. Set a level per competition here or in Run configs → Notifications.

Repository projects#

Repo auto-run sends to the project's own topic: a plan waiting for your approval (high priority), what each launch ran and the best result so far, a pause, a usage limit with its reset time, a launch stopped at its time limit, and the daily summary.

Alerts tell you; the dashboard decides#

An alert is plain text. When it says a decision is waiting — a submission or a plan — you make it on the dashboard under the 🔔 or in a terminal, so nothing is approved from a notification by accident. Under the 🔔 the questions are grouped by competition, each section showing its count and the Kaggle submissions left today. Some answers are marked ⚙: picking one also changes a Run configs setting, such as switching compute, after you confirm. See Answers that change a setting and Submissions and approvals.

Telegram instead#

$ export TELEGRAM_BOT_TOKEN=…
$ export TELEGRAM_CHAT_ID=…