How to add a project

← all projects

No redeploy, no restart. A project is just a folder:

projects/<slug>/
  meta.json    — name, description, tags, links
  config.json  — refresh_seconds, fields[] to display, done_when
  status.json  — written by YOUR listener/runner (atomically: tmp + rename)
  page.html    — optional custom detail page, served at /projects/<slug>/page
  metrics.jsonl — optional append-only log, last 50 rows shown

1. Copy the template

cp -r templates/project projects/my-project
# edit projects/my-project/meta.json and config.json

2. Define what to show (config.json)

{
  "refresh_seconds": 10,
  "fields": [
    {"key": "step", "label": "Step", "kind": "number"},
    {"key": "epoch", "label": "Epoch", "kind": "progress",
     "progress_source": {"current_key": "epoch", "total_key": "total_epochs"}},
    {"key": "loss_total", "label": "Loss", "kind": "number"},
    {"key": "status", "label": "Status", "kind": "status"}
  ],
  "done_when": {"progress_key": "epoch", "at_total": true}
}

Field kinds: text, number, progress (needs progress_source with current_key/total_key), status, eta, timestamp. Keys can be nested, e.g. tasks.invsqrt.cost.

3. Wire a listener — two ways

A. File write (simplest, same machine): your runner writes status.json itself, atomically, every N steps. See templates/listener.py — stdlib only, write_status() + log_metric(). The server re-reads the file on every API request, so it appears within one poll (default 10s).

B. POST from anywhere (desktop, Kaggle, another host):

curl -X POST https://tracker.simplysoup.myaddr.io/api/projects/my-project/status \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -d '{"status":"running","step":120,"total_steps":1000,"loss_total":0.42}'

The server merges the fields into status.json and stamps updated_at. The API key is Bearer-only; only its SHA-256 is stored on the server.

C. Remote file source: in config.json set "source": {"type": "file", "path": "/absolute/path/to/status.json"} and the server polls that path on every request instead of the project's own status.json.

4. Check it

curl https://tracker.simplysoup.myaddr.io/api/projects/my-project
# or open the index and search for the project name — it appears within ~10s

API

GET  /api/health                  {"ok":true,"service":"research-tracker"}
GET  /api/projects                all projects (meta+config+status, no metrics)
GET  /api/projects/<slug>         one project, incl. last 50 metrics rows
POST /api/projects/<slug>/status  Bearer API key, merges JSON into status.json
GET  /projects/<slug>/page        custom page.html, if the project has one