Training watch
Passive observer for external training runs. Not aquin simulate and not checkpoint SAE tools. Your trainer (PyTorch loop, custom script, Aquin SDK, etc.) writes metrics as JSONL; aquin watch ingests those lines and stores them locally under ~/.aquin/watch/<run_id>/ (manifest.json + events.jsonl). Aquin does not run optimizer steps or store merged weights here. For post-training SAE diff on checkpoints, see Checkpoint SAE (/docs/checkpoint-sae). Simulation runs stay in ~/.aquin/runs/ and appear only under aquin list simulation. Watch does not require a loaded model.
4 commands
aquin watch list
List local watch runs: run id, status, name, base model, event count.
aquin watch init
Register a watch run before ingesting metrics. Writes manifest.json and a start event to events.jsonl under ~/.aquin/watch/<run_id>/.
| Flag | Description |
|---|---|
| --name | Display name (default: watch-run). |
| --model | Base model slug shown on charts (e.g. llama-3.2-1b). |
| --quant | Quantization label: fp16, int8, q4, none (default: none). |
| --mode | Run mode label (default: external). |
aquin watch ingest
Parse a metrics JSONL file and append observations to a watch run. Batch mode (default) reads the file once and exits. With --follow, keeps tailing the file as new lines are appended (live training).
| Flag | Description |
|---|---|
| --run | Existing watch run id (from init or list). |
| --name | With --file and no --run: override new run name. |
| --file | Path to metrics JSONL. Omit to read stdin. |
| --follow | Tail the file; ingest new lines as they appear. |
| --finish | Mark run stopped when ingest ends. |
| --map src=dst | Rename a metric column (e.g. --map train_loss=loss). |
| --step-field | Step column name (default: step, global_step, …). |
| --offset | Skip first N lines (resume ingest). |
| --auto-step | Assign steps 0,1,2… when rows have no step field. |
Fixture: fixtures/e2e/watch/metrics.jsonl. One JSON object per line. Scalar keys (loss, learning_rate, grad_norm, epoch) become chart channels. Special rows: {"type":"signal",…} and {"status":"stopped"}.
aquin watch <run_id>
Replay or live-tail the local events.jsonl for a run. Default follows new events (Ctrl+C to detach). --no-follow replays once and exits.
| Flag | Description |
|---|---|
| --no-follow | Replay stored events once; do not wait for new lines. |
Quick start
Watch does not run GPU inspection on your metrics file and does not require a loaded model. Metrics are stored locally under ~/.aquin/watch/.
Live training (--follow)
Point ingest at a metrics file your trainer appends to. Each new JSON line is picked up automatically.
Metrics JSONL format
One JSON object per line. Step comes from global_step, step, or --step-field. Numeric scalars become chart channels. Use --map train_loss=loss to rename trainer column names.
Watch vs simulate
| Training watch | aquin simulate | |
|---|---|---|
| Purpose | Observe real external training metrics | Forecast training without weight updates |
| Storage | ~/.aquin/watch/<run_id>/ | ~/.aquin/runs/<run_id>/ |
| List command | aquin watch list | aquin list simulation |
| GPU | Not required | Required (model load) |
| Web | Local JSONL only | Tracked + CLI inbox when logged in |
For SAE diff / temp train / align on real checkpoints after training, see Checkpoint SAE. Watch does not store merged weights or run GPU SAE tools.