exea.md
One file at the top of your repository tells the runner everything it needs. It is the only file we read. Five headings, five commands — fill them in and your job runs unattended.
exea.md goes at the very top of your repository — the same directory as your README.md, not inside src/, docs/, or any other folder. The runner looks in exactly one place and does not search.
your-repo/ ├── exea.md ← here, at the root ├── README.md ├── requirements.txt └── src/
Replace the commands with your own. Keep the headings exactly as written — the runner matches on them.
---
exea_version: 1
owner_email: you@example.com
github_username: your-github-username
# The runner injects your token as $EXEA_GITHUB_PAT at run time.
# You submit it once at reserve.exealabs.org/dashboard.
# NEVER write the real token in this file — this repo is public.
github_pat: ${EXEA_GITHUB_PAT}
# Where checkpoints live, relative to the repo root. This directory is what
# gets snapshotted at 13:00 and restored at 10:00 the next day.
checkpoint_dir: ./checkpoints
---
# exea.md
One line describing what this job does.
## SETUP
Runs once per session, before START or RESUME. Install dependencies here.
Must be safe to run repeatedly — it runs again every day the job resumes.
```bash
pip install -r requirements.txt
```
## START
Runs only on the FIRST session, when no checkpoint exists yet.
Must write checkpoints into $EXEA_CHECKPOINT_DIR on a regular interval.
```bash
python train.py --checkpoint-dir "$EXEA_CHECKPOINT_DIR" --save-every 300
```
## RESUME
Runs on EVERY session after the first. Must load the newest checkpoint from
$EXEA_CHECKPOINT_DIR and continue — not restart from scratch.
```bash
python train.py --checkpoint-dir "$EXEA_CHECKPOINT_DIR" --save-every 300 --resume
```
## STOP
Runs at 13:00 PST, before the machine is snapshotted. Must flush a final
checkpoint to disk and exit within 120 seconds. If --save-every already wrote
everything you need, a graceful shutdown is enough.
```bash
kill -TERM "$EXEA_JOB_PID" 2>/dev/null || true
wait "$EXEA_JOB_PID" 2>/dev/null || true
```
## SAVE
Runs after STOP. Commits and pushes whatever you want kept in git.
Git is already authenticated with your token — just add and push.
Do NOT push multi-gigabyte checkpoints; those live in the disk snapshot.
```bash
git add -A results/ logs/ metrics.json
git commit -m "exea: session $EXEA_SESSION_COUNT results" || echo "nothing to commit"
git push origin HEAD
```
These are exported before any of your blocks run. Use them instead of hardcoding paths or guessing whether you are resuming.
Your repository is public. The github_pat line in the template is the literal placeholder ${EXEA_GITHUB_PAT} and must stay that way. You submit the real token once on your dashboard; the runner injects it at run time. A token pushed to a public repo is read by scrapers within minutes and revoked by GitHub — your pushes will start failing and you will lose the session.
Three hours is not much. Save every few minutes, not every epoch. A checkpoint should contain model weights, optimizer state, the step or epoch counter, your position in the dataset, and RNG state — everything needed for RESUME to be indistinguishable from never having stopped.
Test it locally before you book: start your job, kill it, run your RESUME command, and confirm it picks up where it left off. That is exactly what the runner will do to it.
Add your GitHub credentials, then claim a slot.