Skip to main content
Onyx uses three core objects.

​
Project

A project is an internal Onyx record for a GitHub repository, optionally scoped by projectPath. Onyx creates or reuses it automatically when the first branch starts from that repository. Onyx stores project metadata for search, permissions, graph rendering, and repository sync, while git remains the source of truth for code.

​
Branch

A branch is a research direction. Each Onyx branch maps to one git branch: 
onyx/{name}
Branches track:
  • name and description;
  • metric name;
  • metric unit;
  • direction, either maximize or minimize;
  • base commit;
  • best experiment and best metric.

​
Experiment

An experiment is one recorded run at one commit. Experiments track:
  • commit SHA;
  • status;
  • primary metric value;
  • secondary metrics;
  • agent notes;
  • output summary;
  • optional checks result;
  • previous best commit for diffing.
The server owns ordering, best-so-far lineage, and sequence numbers. Clients report facts.