Frequently Asked Questions

How does roar work?

roar ships three tracer backends — eBPF, preload (LD_PRELOAD on Linux, DYLD_INSERT_LIBRARIES on macOS), and ptrace — and picks one automatically. Each observes file I/O across the whole process tree (including fork/exec) by hooking the relevant syscall surface; events stream out to a userspace daemon, which derives the artifact records and the DAG.

For the full backend story, tradeoffs, and the comparison table: Tracers.

What does roar run on?

Linux and macOS. The eBPF backend additionally requires Linux ≥ 5.8 with BTF; the preload backend covers macOS and the rest of Linux; ptrace is the fallback when neither of the others is usable.

For platform-specific notes, including a cloud-provider compatibility table for eBPF: Tracers → Platform notes and Tracers → Cloud and managed GPU platforms.

How are artifacts recognized?

roar categorizes every file the tracer sees:

• System files (/usr, /etc, /proc, /dev, /lib, …) — filtered out.
• Package files (Python site-packages, virtualenv, stdlib) — not treated as data inputs; recorded as packages on the job instead.
• Artifacts — what's left. Files your code actually read or wrote that aren't system/package noise. These become the tracked inputs/outputs in the DAG.
• Composite artifacts — when the tracer sees directory-shaped output (Lance, Zarr, sharded parquet, etc.), roar records the whole directory as one artifact rather than each component file separately. See Composite Artifacts.

Are artifact hash collisions possible?

Practically, no. blake3 is a 256-bit hash; the birthday-bound collision probability for 2⁶⁴ (≈ 1.8 × 10¹⁹) registered artifacts is on the order of 2⁻⁶⁴ — about one in 18 quintillion. The same math holds for sha256. The probabilistic risk of accidental collision isn't a deciding factor for either algorithm.

For why we chose blake3 anyway, and when sha256 is worth computing alongside: Hashes.

Why is roar hash-agnostic?

Different ecosystems standardize on different hashes — Hugging Face on sha256, git on sha-1 (transitioning to sha256), Docker on sha256, IPFS on its own multihash family. Pinning roar to a single algorithm would create artifact-identity gaps at every ecosystem boundary.

The model is: each artifact in roar's DB has one or more hash entries (blake3, sha256, etag for S3, …) and roar looks up by any of them. Primary is blake3; additional algorithms get computed when configured per operation. See Hashes.

Why clean commits?

Every recorded roar job carries a git commit SHA, and that SHA is the answer to "what code produced this artifact?" If the working tree was dirty at run time, the commit alone is no longer enough information to reconstruct what actually executed — you'd need that commit plus whatever local edits existed at the time, which may or may not still exist on any machine. In practice, that means: not reproducible.

roar blocks rather than warns because lineage trust is binary. A downstream consumer of a registered DAG has no way to selectively distrust a dirty-tagged step partway up the chain — once one job's code state is uncertain, every artifact derived from it inherits that uncertainty. Making the dirty case loud and refuse-by-default keeps the rest of the graph honest.

The escape hatches:

• roar run --allow-dirty <command> — proceed anyway. The job records dirty: true, the dirty file list is captured, and roar show surfaces both. You can filter dirty jobs out of roar dag (or out of a registration) when you don't want them showing up in the audit trail.
• The .roar/ only case — if the only dirty path is .roar/ itself (typically right after roar init before you've committed the .gitignore change), roar run prints the quick fix inline. Most users hit this once and never again.
• Running from $HOME — if you're invoking roar from your home directory rather than a project, roar detects that specifically and points you at the project-directory pattern. Your home directory is rarely meaningfully version-controlled, so the dirty check there would be theatre.

For the full error message walkthrough — including the per-symptom remediations — see Troubleshooting → Git repository has uncommitted changes.

Why does roar tag git commits?

Every job records git context: repository, branch, commit, dirty/clean state.

When a DAG is registered to GLaaS, the relevant commits may also be persistently tagged on the remote so that:

• Provenance stays stable as branches move or get rebased.
• Reproduction doesn't depend on a particular clone's local history.
• The lineage outlives any one machine or workspace.

Can I register without an account?

Yes — the anonymous scope is the default for new roar init workspaces, and roar register works without a login. The artifact's existence becomes globally lookup-able by hash; no account is attached.

For private or attributed publishes, roar login (free) is the recommended workflow. After logging in, the workspace's scope auto-flips from anonymous to private and your registrations become access-controlled. See Scopes.

Does roar slow down my training?

The overhead breakdown:

• Startup: 50–200 ms per roar run for backend selection and tracer init.
• Per-syscall: very low under eBPF and preload; meaningfully higher under ptrace (two context switches per syscall).
• Post-run hashing: content hashes for output files. Dominated by large outputs; blake3 throughput on modern hardware is in the multi-GB/s range.

For a typical multi-minute training run the total overhead is in the low single-digit percent. For sub-second commands, the startup cost is a noticeable fraction of total runtime — see Tracers for backend-specific overhead numbers and Benchmarks for the data.

Can I use roar without GLaaS?

Yes. Everything except roar register and roar reproduce <hash> (for hashes you don't already have locally) works fully offline. The local .roar/roar.db is the source of truth for your own lineage; GLaaS adds the global registry layer for sharing and cross-machine reproduction.

Does roar work in containers?

Mostly yes, with backend-specific caveats:

• preload is the safest default for containers — no kernel deps, no privileged mode.
• eBPF requires host-kernel access; most managed container runtimes don't expose this.
• ptrace works in most setups but is slower; some seccomp/YAMA policies block it.

See Tracers → Containers / CI for the matrix.