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 campaign 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.

​
Campaign

A campaign is a research direction. It is a logical Onyx track, not a mutable git history branch. Campaigns track:
  • name and description;
  • metric name;
  • metric unit;
  • direction, either maximize or minimize;
  • base commit;
  • setup, hypothesis, worker, session, and summary state;
  • best experiment and best metric.
Campaign status is one of active, completed, or archived. Deletion is tombstone-based and does not rely on a mutable campaign status.

​
Experiment

An experiment is one recorded run with an immutable result commit. Experiments track:
  • base commit SHA;
  • result commit SHA;
  • result ref, usually refs/onyx/experiments/<campaignId>/<runRef>;
  • status;
  • primary metric value;
  • secondary metrics;
  • agent notes;
  • output summary;
  • optional checks result;
  • optional setup, hypothesis, worker, and provenance links.
The server owns best-so-far projection, worker visibility, hypothesis state, summaries, knowledge, provenance, worker leases, and accepted experiment order. Clients report facts directly through /api/v1; experiment reports include pushed immutable result refs so git verification and best projections can update after server-side validation, while explicit reconcile repairs stale projections later.