> ## Documentation Index
> Fetch the complete documentation index at: https://onyxresearch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects, Campaigns, and Experiments

> Understand the core Onyx research model.

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.