Epokio

Epokio reads the training logs you already have and alerts your phone when a run stalls, hits NaN, or finishes. No code changes, no account: it reads what YOLO, Hugging Face, Lightning, Keras and TensorBoard already write. Works over SSH.

Quick start

Python 3.10 or later, on Windows, macOS or Linux. In a terminal in your project folder, on the machine that trains:

pip install epokio
epokio setup
epokio watch --once

epokio setup finds your runs, starts the helper (a small background program that reads the logs and sends the alerts) and opens its page. epokio watch --once prints the same list in the terminal. Setup looks in this folder and in Desktop, Documents, Downloads, Projects and ~/runs, inside your user folder. Runs somewhere else, like D:\ or /data? Name the folder: epokio setup --root D:\myproject\runs. On Windows, if pip or epokio is not recognized, put py -m in front: py -m epokio setup. If pip stops with externally-managed-environment (Ubuntu 24.04, Homebrew Python), use a virtual environment or a conda env (how).

On a shared GPU server over SSH

No sudo needed. In your own account on the server (a conda env works too):

python3 -m venv ~/.epokio-venv && ~/.epokio-venv/bin/pip install epokio
~/.epokio-venv/bin/epokio setup --root /data/you/runs --autostart

--autostart writes a systemd user service, so the helper survives SSH logout and reboots. To keep it running after you log out, setup turns on linger (loginctl enable-linger $USER); if the server refuses, an admin runs sudo loginctl enable-linger <you> once. epokio doctor says in one line whether the helper runs now and comes back. Setup prints an SSH tunnel such as ssh -N -L 18787:127.0.0.1:8787 <server> for your own computer, then http://127.0.0.1:18787/ shows the server's runs; epokio watch works in plain SSH. Other accounts on the server can read a helper on 127.0.0.1, so on a shared machine see limits.

Phone alerts in 3 steps

1. Install the ntfy app on your phone and subscribe to a topic only you know (letters, digits, - and _).
2. Save it on the training machine, with your topic in place of your-secret-topic: epokio alerts --add https://ntfy.sh/your-secret-topic
3. Check it: epokio alerts --test

From then on, the helper sends an alert when a run finishes, fails (NaN loss or a crash) or stalls (no new epoch for well past its usual pace, 3 minutes at least). Slack, Discord and Telegram webhooks work the same way (https only). Alerts go out only while the helper runs. epokio setup --autostart keeps it running after logout and reboot without sudo (a systemd user service on Linux, a LaunchAgent on macOS, the Startup folder on Windows). epokio doctor shows whether it runs now and starts again; epokio doctor --test-alert sends a real test alert.

What you get

• One live list of every run: progress, time left and best score, whatever framework wrote the log.
• Curves with a plain-language note. It marks the epoch with the lowest validation loss and says when the score starts to fall.
• On your phone too. epokio setup --lan prints the address and a view-only token, which shows everything and hides every button that changes something.
• Also in a terminal (epokio watch, good over SSH), a tray icon on Windows and Linux, and a macOS menu bar app.
• No account, no upload. Only the alerts you add leave the machine.

Notebooks and Colab

Where no helper can run, the training process sends the alert itself:

!pip install epokio
!epokio alerts --add https://ntfy.sh/your-secret-topic

import epokio
with epokio.start("runs/colab-exp", epochs=20, notify=True) as run:
    for epoch in range(20):
        ...
        run.log(train_loss=tl, val_loss=vl, acc=acc)

You get an alert when the block ends, or when it raises (with the error). A network failure never stops training.

Security defaults

• The helper listens on 127.0.0.1 only. setup --lan opens it to your network and then asks for a token.
• Starting training, queue jobs and sweeps from the page (and from MCP) is off. epokio config launch_runs on turns it on and shows the Train, Queue and Sweeps tabs.
• New tokens are view-only; epokio agent --add-token NAME --scope run makes one that can change things.
• A --lan helper runs nothing sent over the network unless it was started with --allow-run.
• On a shared server, other accounts can read a helper on 127.0.0.1. Over SSH on Linux, epokio setup asks to make viewing need a token too (reads_token always, on by default without a terminal, --no-lock-reads skips it; the page then asks for epokio agent --show-token once). Elsewhere run epokio config reads_token always. Then give each person a token limited to their folders (how).
• The helper speaks plain HTTP. Prefer an SSH tunnel or Tailscale over --lan. Details: docs/remote.md.

Compared with other tools

Checked against each project's README and docs in October 2026. Epokio can read TensorBoard event files and W&B's local files, so it can sit next to them.

More columns (MLflow, Aim, Ultralytics Platform, price): docs/guide.md.

Supported formats

Ultralytics YOLO, Hugging Face Trainer, PyTorch Lightning (CSVLogger), Keras (CSVLogger or the TensorBoard callback), TensorBoard event files and W&B local files (neither needs to be installed), timm, OpenMMLab, MAE/DeiT-style log.txt, and your own loop: epokio.start, or a CSV whose first column is epoch, step, iter or iteration. Which file each one reads, planned epochs and best-score rules: docs/guide.md.

More

Guide (alerts, limits, full comparison, privacy, troubleshooting) · Mac app · Remote helpers, Windows app, tray, phone · AI assistants (MCP) · Uninstall · Changelog · Contributing

Something wrong? Run epokio doctor and paste the output into an issue (it never prints your token). License: MIT.