Guide to Using roar from Start to Finish

Installing roar

Recommended (fast, reproducible Python tooling):

uv pip install roar
# or for development:
uv pip install -e .

roar currently requires Python 3.10+.

Configuring roar (roar init)

In your project repo:

cd my-ml-project
roar init

This:

• creates .roar/ (local DB + cache)
• offers to add .roar/ to .gitignore
• configures defaults (including the default GLaaS server, if set)

You can inspect and modify configuration via:

roar config list
roar config get <key>
roar config set <key> <value>

Building (roar build)

Use roar build for setup steps you want tracked separately from your "main" DAG steps—e.g., compiling extensions or installing local packages.

roar build pip install -e .
roar build make -j4

Build steps can be replayed as part of reproduction when needed.

Running (roar run)

roar run python train.py --epochs 10 --lr 1e-3
roar run ./scripts/preprocess.sh
roar run torchrun --nproc_per_node=4 train.py

roar observes file I/O across the full process tree, then updates jobs, artifacts, and the inferred DAG.

The current DAG (roar dag)

As you iterate, you may re-run commands, overwrite outputs, or change downstream results. roar retains history, but roar dag shows what is true now.

roar dag

The current DAG:

• collapses re-runs
• keeps only the most recent equivalent job
• hides downstream work that depends on overwritten inputs

This is a projection of history, not a deletion of it.

Setting up authentication with glaas.ai (roar auth)

To register artifacts on glaas.ai you'll need to register your public key with glaas.ai.

First step is to grab your public key. You can do this with:

roar auth register

This will print your public key to the terminal.

Copy the text of your public key and then go to glaas.ai and in the upper-righthand part of the page, click on "Sign in with GitHub".

After signing in using your GitHub account, go back to the GitHub login name shown in the upper-righthand part of the page again and click "SSH key" where you can paste your public SSH key.

Go back to the terminal to test your setup:

roar auth test

Registering DAGs with GLaaS (roar register)

When you run:

roar register <path to artifacts>

roar registers a Registered DAG:

• includes the selected artifact(s)
• includes upstream jobs and artifacts required to explain them
• forms a self-contained recipe for reproduction

This is what GLaaS stores and makes searchable.

After registration, use glaas.ai to visualize and navigate the Registered DAG by clicking between artifacts, jobs, and sessions.

Reproduction (roar reproduce)

When you run:

roar reproduce <artifact-hash>

roar reconstructs a recipe DAG:

• describes steps required to recreate an artifact
• contains planned steps, not completed jobs
• may reference artifacts that do not yet exist

As you execute steps:

• planned steps become real jobs
• artifacts are created
• the recipe merges into your active session

On glaas.ai, artifact pages provide a "Reproduce with roar" action to generate the reproduce command.