Skip to main content
Onyx research is remote-first. Supabase and the /api/v1 API own projects, campaigns, sessions, hypotheses, worker leases, lifecycle state, experiment acceptance, summaries, knowledge, best projections, stop state, and git verification. Local workers still run in your checkout, but they report directly to the API instead of writing a local research database and replaying events later. .git/onyx/ remains important, but it is runtime storage, not the product source of truth. It keeps logs, workflow files, manifests, lock files, and recovery hints that help humans understand or salvage local work.

​
Local Runtime Files

Onyx stores local runtime artifacts under .git/onyx/. These files are safe to delete when you intentionally reset local runtime state, although doing so may remove useful recovery information for in-flight workers. They are not an offline campaign ledger.

​
Online Requirement

Research product commands require API access. Campaign setup, session creation, worker lease acquisition, worker heartbeat, experiment reporting, summaries, knowledge, status, stop, and list commands read or write server state directly. If the API is unavailable, the command fails visibly instead of hiding the work behind a durable pending queue. Workers still preserve local evidence when something goes wrong. For example, if a worker successfully commits but cannot push the immutable result ref, its manifest records the branch, commit, intended ref, and recovery instructions. If it pushes the ref but the API report fails, the manifest records the pushed ref so an operator can inspect or repair it.

​
Worker Leases and Acceptance

The server owns worker slots and accepted experiment ordering.
  • Before launching provider processes, the supervisor asks the API for worker leases in idempotent batches. Each grant includes the worker id, lease token, expiry, assigned hypothesis, campaign/session context, and project/git context.
  • The supervisor owns normal batch heartbeat renewal. Direct worker heartbeats remain available as a fallback/debug primitive; terminal heartbeats release slots.
  • Workers push HEAD to an immutable ref such as refs/onyx/experiments/<campaignId>/<runRef> before reporting an experiment.
  • Experiment reports never choose acceptedIndex. Report requests record or deduplicate quickly; server settlement later assigns accepted/discarded disposition and accepted indexes.
  • Late reports are preserved as discarded diagnostics for lineage/debugging but do not count toward session targets, rankings, or best projections.

​
GitHub Repository Sync

The word “sync” still appears in one place: repository metadata refresh through the GitHub App. That process updates installation metadata, repository access, default branch heads, and code-read availability. It is separate from research state reporting and is not the old research event-replay layer.

​
Useful Commands

  • status shows the active profile, API target, and cached project/campaign pointers.
  • research status and listen read live server state plus local supervisor runtime files when available.
  • workflow status shows local workflow runs, step summaries, metrics, block reasons, and log paths.
  • exp list, knowledge list, and summary list read remote API state.