Skip to main content
Onyx works with repositories you already own. It does not scaffold a new repository or move your code out of git.

​
Start with the GitHub App

1

Open the app

Go to app.onyxresearch.ai and sign in.
2

Connect GitHub

In Settings → Integrations, click Connect GitHub to install or manage the Onyx GitHub App for the GitHub account or organization. The flow opens in a new tab and includes a GitHub user authorization step that verifies your account can access the installation; it finishes back on Settings → Integrations.
3

Choose a repository

Grant Onyx access to the repository. Onyx records repository metadata and keeps the default branch head fresh through GitHub repository sync.
4

Create the campaign

Use /onyx ... or onyx campaign setup from the local checkout. Pass --project-path when the research work is scoped to a subdirectory.
The GitHub App is used for repository selection, private repository access, installation metadata, webhook updates, repository sync, and code reads. Onyx does not store GitHub installation tokens. Internal project rows are created or reused automatically from campaign creation.

​
Choose a Project Path

Set projectPath when only a subdirectory belongs to the research work. Examples: Paths returned by the app are relative to projectPath, while GitHub code reads still happen against the full repository.

​
Repository Sync Behavior

GitHub webhooks mark projects not_synced and schedule repository metadata sync. The exact source of code remains git, and file trees, blobs, and diffs are read from actual commits through GitHub. This repository sync is distinct from research reporting. Campaigns, sessions, workers, experiments, summaries, and knowledge are written directly to the Onyx API by the CLI and worker commands. In the app, use the repository sync action for the tracked project when repository metadata looks stale.