installation

orcr needs three things on your machine:

1. the orcr binary itself,
2. a running herdr on your PATH, with the integration installed for every provider you want to run, and
3. Node (only if you use orcr scaffold or the TypeScript SDK).

the orcr binary has no other runtime dependency. herdr is the layer below it: persistent named sessions, background TUIs, and the per-provider state detection orcr reads. orcr discovers herdr, it never bundles it.

install orcr

pick one of the three methods.

prebuilt binary

prebuilt tarballs are published on GitHub releases for macOS (macos-arm64, macos-x64) and Linux (linux-x64). each orcr-<version>-<platform>.tar.gz ships a matching .sha256 you can check before extracting.

# optional: verify the download against its published checksum first
shasum -a 256 -c orcr-<version>-<platform>.tar.gz.sha256

tar -xzf orcr-<version>-<platform>.tar.gz && mv orcr /usr/local/bin/

cargo install

if you have a Rust toolchain (Rust >= 1.89):

cargo install orchestratr    # installs the `orcr` binary

the orchestratr crate is not yet claimed on crates.io, so this method does not work today; the prebuilt tarball and build-from-source paths are the working options. see the changelog for release status.

build from source

from a checkout:

cargo build --release        # produces target/release/orcr

confirm the binary is on your PATH:

orcr --version

install herdr and its integrations

orcr talks to herdr over herdr's own socket API and discovers the herdr binary in this order:

1. the herdr.bin key in your orcr config,
2. the $ORCR_HERDR_BIN environment variable,
3. your $PATH.

if none of these resolves to herdr, orcr commands exit with code 2 and print an install pointer. install herdr from herdr.dev first (orcr is verified against herdr 0.7.x).

a provider is supported only when both integration layers are present:

• herdr's integration lets herdr observe the provider (its working/idle/blocked state and the transcript pointer). install it per provider:

  herdr integration install claude
  herdr integration install codex

• orcr's integration is how orcr drives the provider (launch flags, model and effort mapping, completion tuning, graceful shutdown, and the transcript adapter). claude and codex are built into orcr in the first release; you do not install them separately.

if either layer is missing for a provider, orcr agent run -a <provider> fails fast with integration_missing and names the exact fix. nothing is spawned. there is no degraded half-mode.

verify your setup

run:

orcr server status

this auto-starts the orcr server if it is not already running (every CLI call does), then reports the server version and protocol version, the socket and store paths, whether the herdr binary and its socket are reachable and which session orcr owns, live agent counts, loop schedule, and the per-provider integration state.

the integration state is the field to check. both layers must read true for a provider before you can run it:

// orcr server status --json (excerpt)
{
  "integrations": {
    "claude": { "orcr": true, "herdr": true },   // supported
    "codex":  { "orcr": true, "herdr": false }   // run herdr integration install codex
  }
}

Node, only for the SDK

orcr scaffold and the TypeScript SDK need Node >= 20 with npm. the CLI itself does not. if Node is missing or too old, orcr scaffold fails with environment_error and an install pointer, and creates nothing. install Node from nodejs.org if you plan to write workflows in TypeScript.

next steps

• quickstart: CLI drives one agent from the shell.
• quickstart: SDK scaffolds a TypeScript project.
• your first workflow builds a parallel code review end to end.