---
title: Harbor Run Viewer
emoji: 🔭
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

# Harbor Run Viewer

Train and eval runs from the OpenEnv × Harbor stack. **The data lives in a Hugging Face bucket; this app
only renders it.**

## The one design decision

A bucket mounted into a Space appears as an ordinary filesystem path inside the container, so the Space
and a laptop run *the same* code against *the same* layout — `DATA_DIR` is `/data` in one case and
`./data` in the other. There is no local-vs-remote branch to keep in step, and no data in the image.

```
laptop:   DATA_DIR=./data          uvicorn app:app
Space:    DATA_DIR=/data           ← bucket mounted read-only or read-write
fallback: DATA_BUCKET=ns/bucket    ← read a bucket over HfFileSystem without mounting it
```

## Run it locally

```sh
pip install -r requirements.txt
DATA_DIR=./data uvicorn app:app --port 8000     # http://localhost:8000
```

## Publish runs to the bucket

```sh
hf buckets create <ns>/harbor-runs --exist-ok
hf sync ./data hf://buckets/<ns>/harbor-runs           # add --delete to mirror exactly
```

## Point the Space at the bucket

```sh
hf spaces volumes set <ns>/harbor-run-viewer -v hf://buckets/<ns>/harbor-runs:/data
```

Only buckets support read-write mounts; models, datasets and Spaces are always read-only. A private
bucket needs `HF_TOKEN` as a Space secret.

Then press **⟳ Refresh** in the UI: it drops every cache and rescans. A mounted bucket already reflects
new writes, so nothing needs rebuilding or restarting to see a run that finished a minute ago.

## Layout

See [CONTRACT.md](CONTRACT.md). Briefly: one directory per run under `runs/<run_id>/`, identified by a
`run.json`, with optional `eval/summary.json` and `train/metrics.jsonl`. A run with only training data
renders as training; one with both shows both; nothing is required beyond `run.json`.

Two conventions in that contract carry real meaning rather than being formatting:

- **`reward: null` is not zero.** It means the verifier never ran — a dead sandbox, no answer. Those
  attempts are excluded, and a task whose every attempt is null is counted as *unmeasured*. Averaging
  them in as zeros makes infrastructure failure look like a weak model.
- **`reward_std` sits next to `reward`.** A step whose generations all score the same has zero advantage
  and teaches nothing, so the viewer reports *steps with a gradient* — a reward curve alone cannot
  distinguish learning from a flat run.