Use large-scale AI agent teams to rapidly discover code improvements on your hardware systems.
# One-line installer
curl -fsSL https://onyxresearch.ai/install.sh | bashThe installer places onyx in ~/.local/bin (override with
ONYX_INSTALL_DIR), walks you through PATH setup if needed, and opens browser
login on a local desktop. SSH sessions use device authorization instead. Press
Ctrl+C to authenticate later with onyx login. Installs without a controlling
terminal skip login rather than waiting; set ONYX_INSTALL_NO_PROMPT=1 to skip
all interactive setup explicitly.
Onyx includes a CLI, but the intended interface is to use onyx with your coding agent, via the /onyx skill included.
Open your coding agent inside the repository you want to improve and run:
# Set up your repo to work with Onyx, no tutorial needed
/onyx Help me setup my project to run onyx researchOnyx will then do the setup for you while you provide input on things like the goal, metric, editable scope, and reliability/evaluation tooling. Onyx can scaffold its own metric evaluation tools, and then kick off a research session for you that can be steered at any time.
You can watch an active research session from a new terminal in the same directory with the CLI below, or using the Onyx platform.
# Watch the research session from a new terminal in the same repo
onyx listenOnce you have a research session running, continue using your main-thread coding agent that you ran /onyx from to steer the research.
# Using same /onyx coding agent thread from earlier
Can you stop researching the PID controller, and instead build on the MPC controller more?
# Orchestrator agent uses CLI for you to steer the research... ┌──────────────┐
│ You │
└──────────────┘
▲
│ Direct your requests through the Onyx agent.
▼
┌──────────────┐
│ Orchestrator │
│ /onyx │
└──────────────┘
│
┌──────────────┼────────────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Worker 1 │ │ Worker 2 │ ··· │ Worker N │
└────────────┘ └────────────┘ └────────────┘
│ │ │
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Experiments│ │ Experiments│ ··· │ Experiments│
└────────────┘ └────────────┘ └────────────┘
Onyx uses a mix of deterministic CLI/processes with agents to keep research consistent, and results durable across sessions. Every experiment is a git commit with metrics and metadata so that the results can easily be turned into PRs once code improvements are found.
Every session is bounded: pass --experiments <n> for an exact accepted
experiment target, --max-minutes <n> for a deadline, or both. Scale a
running session with onyx research scale --workers <n> and stop it
gracefully with onyx research stop.
| Agent | Support |
|---|---|
| Claude Code | Built-in launcher (--agent claude) + auto-installed /onyx skill |
| Codex | Built-in launcher (--agent codex) + auto-installed /onyx skill |
| OpenCode | Built-in launcher (--agent opencode) + auto-installed /onyx skill |
| Custom harness | Bring your own worker with --worker-command (see CONTRIBUTING.md) |
Built-in launchers spawn provider CLIs directly in non-interactive mode — no extra configuration beyond having the provider CLI installed and authenticated.
- Installation and Quickstart
- Concepts
— projects, campaigns, experiments, metrics, and the
onyx/directory - CLI reference
- Onyx platform — review experiments, manage teams and API keys
bun install
bun run ciTo point the installed onyx command at this checkout, run
onyx developer link . then onyx developer use dev; switch back with
onyx developer use release. See CONTRIBUTING.md for the
full contributor guide, including skill/prompt regeneration, release builds,
and the custom harness contract.
onyx research recover --dry-run --json inspects pending reports; omit --dry-run
to attempt bounded delivery. Supervisors recover every 30 seconds while running.
Frozen report bodies and immutable local refs survive network failures and cleanup.
Recovery pushes saved commits even after their worktrees are removed. An acknowledged
report with a failed push stays pending until its ref reaches origin; retries never
change its frozen report body. Independent attempts report concurrently, and recovery
skips attempts currently owned by a foreground reporter.
Unsupported old records are retained for inspection, not converted automatically.
research clean refuses active or pending execution state and preserves recovery evidence.
Locks never expire under a holder. After stopping all users of a resource, use
onyx research locks reset --resource <name> --confirm-idle [--dry-run].
Internal push and drainer locks are onyx-result-ref-push and onyx-report-delivery.
Per-attempt locks use onyx-report-attempt-<sha256 of runRef>; errors identify the
specific resource and lock path.
A missing PID alone does not prove its descendants stopped. Kernel-lock activation
remains gated on compiled tests on every release target.
Run bun scripts/verify-lock-descriptors.ts to compile and execute the descriptor
feasibility checks on the current host. The Compiled lock proofs workflow runs
them on macOS and Linux, each on ARM64 and x64. The checks cover launcher death,
shell and Git descendants, explicit descriptor closure, timeout escalation, spawn
failure, and final release. Passing these probes does not enable kernel locks;
the production adapter and its integration tests still require a separate change.
macOS can require separate Keychain approval when switching from source execution through Bun to a downloaded CLI, or when the executable identity changes. A keyring timeout means access is unavailable; it does not mean the login was revoked. Onyx retains the profile in this case.
Use the same execution mode that created the login, or run onyx login using the
intended CLI to complete a fresh browser/device login. Login creates a new
credential entry and only replaces the profile after storing it successfully.
If you intentionally switch from a linked source checkout to the release, run
onyx developer use release first. Do not delete Keychain entries or copy refresh
tokens as a workaround. See Apple's
Keychain access guidance.
See the Windows guide for
release availability and qualification of Windows 11 x64, WSL2 and Ubuntu 24.04.
Use Linux-local
repositories, common Git directories, credentials and providers. Automatic login
uses device authorization under WSL; explicit browser/device flags still override.
The main /onyx agent must execute commands inside the same Linux distribution.
Windows-native tools, WSL1, Windows ARM64 and Windows/network-mounted research
storage are outside this target. Compiled Linux releases do not require Bun.
The WSL guards and runtime recovery described here require version 0.1.20 or newer;
an older published release does not include them. A successful install
alone does not qualify Windows support. Distribution termination can leave the
Linux boot ID unchanged, so recovery also verifies process start identity.
Use onyx research recover --runtime [--session <id>] [--dry-run] [--json] to
reconcile interrupted local execution before bounded delivery. Dry-run does not
create runtime files, refresh credentials or change remote state. JSON keeps the
delivery summary and adds runtime.recovered, runtime.skippedActive,
runtime.blocked, and bounded session actions/reasons. Blocked runtime recovery
returns a nonzero status; pending report delivery is reported separately.
Recovery verifies site/run ownership and boot/process identity, skips healthy
supervisors, and retains artifacts when descendant termination is uncertain.
It preserves terminal refs before removing disposable worktrees and credential
homes, then acknowledges terminal worker leases and site cleanup for the matching
site/run. Missing authentication leaves an incomplete receipt for a later runtime
recovery pass. Explicit recovery never changes the remote session cutoff; stop an open
session explicitly. Occupied resource slots require the existing idle reset,
including onyx-runtime-reconciliation after an interrupted launch/recovery.
Malformed evidence is retained. Repeated recovery never measures scratch work or
resumes a session. Clean refuses unresolved runtime and removes worktrees through
Git before deleting logs.
Linux crash recovery requires matching worker protocol-6 onyx and onyx-worker
binaries. Managed evaluator groups and their CLI parents have private boot/PID/start
identity records under the worker runtime directory. Recovery retains uncertain or
legacy ownership evidence; research clean requires completed cleanup acknowledgement.