orchestra

Appearance

Setup ​

How to stand up orchestra for your own organization.

Quickest path: one-line install ​

On a fresh Ubuntu 24.04 VM:

bash
curl -fsSL https://raw.githubusercontent.com/predlico/orchestra/main/install.sh | sudo bash

install.sh clones the repo to /opt/orchestra, installs the system prerequisites (packages, Node, Caddy, the claude CLI + ccr router, the service user, and a build), then launches the interactive orchestra init wizard on your terminal. Override the source with ORCHESTRA_REPO_URL, ORCHESTRA_REF, or ORCHESTRA_REPO_DIR env vars.

The wizard (no LLM) walks you through the whole thing — project identity, which agents to enable, their cadence, repo scopes, integrations, secrets, and operators — then provisions the VM step by step, asking for confirmation before each action (writing config, secrets, systemd units, ccr config, applying the schema, and a final /health check). It loads any existing config as defaults, so it doubles as an editor you can re-run with sudo orchestra init.

Already have the repo on the box? Split the two halves yourself:

bash
sudo ORCHESTRA_PREREQS_ONLY=1 ./scripts/provision.sh   # system prerequisites only
sudo orchestra init                                    # configure + start (wizard)

Every operator action is a subcommand of one CLI — orchestra init, orchestra provision, orchestra tui, orchestra deploy, and so on (run orchestra with no arguments for the list). Before the CLI is installed on PATH, call it from the clone as ./scripts/orchestra <cmd>.

The manual steps below document what the wizard does under the hood (and how to do it fully by hand, including a headless orchestra provision with defaults).

0. Rename (optional but recommended) ​

The repo ships under the neutral name orchestra. To rebrand — this rewrites the project token across systemd unit names, the CLI, the Unix user/group, install paths (/opt/<name>, /var/lib/<name>, /etc/<name>), the DB filename, the ORCHESTRA_* env prefix, and prose:

bash
./scripts/orchestra rename <your-name> --org <github-org>

<your-name> must be a lowercase DNS/systemd-safe token ([a-z][a-z0-9-]*). After running, review the diff and finish the manual edits it prints: config/project.env, Caddyfile (FQDN + ACME email), and routing.yaml repo scopes. The rest of this guide assumes the default name orchestra.

1. Configure identity ​

Edit config/project.env — the single place that documents your org-specific values (GitHub org, product-repo glob, git bot identity, public FQDN, ACME email, deploy target).

Then set your repo scopes in routing.yaml:

  • agents.*.repo_scope — which repo(s) each agent may touch. Single-repo agents (maintainer, builder, documenter, memoriser, auditor) are locked to this harness repo. Repo-agnostic agents (reviewer, developer) use your product-repo glob (default example-*).
  • scheduled[].repo and scheduled[].prompt — what each timer-driven agent runs.

2. Prerequisites ​

  • A small Linux VM (2 vCPU / 4–8 GB RAM / ~40 GB disk). Ubuntu 24.04 LTS.
  • Node.js 22+, git, sqlite3, and the claude CLI on the VM.
  • ccr (@musistudio/claude-code-router) — orchestra routes all Claude CLI calls through ccr so you can swap models per agent without editing prompts. provision.sh installs and configures it. If you prefer to call the Anthropic API directly, point ANTHROPIC_BASE_URL at the API and skip ccr — but the default, tested path is ccr.
  • Caddy for TLS termination in front of the listener (auto Let's Encrypt).

3. Provision the VM ​

bash
# place the repo at /opt/orchestra (git clone or rsync), then:
sudo ./scripts/orchestra provision

provision.sh (idempotent) installs Node, Caddy, the claude CLI + ccr, creates the orchestra service user, state dirs, and systemd units, applies the DB schema, and writes a blank /etc/orchestra/secrets.env stub.

For local development instead of a VM:

bash
./scripts/bootstrap-local.sh    # state under ./local/ (gitignored)

4. Secrets ​

Copy the template and fill in real values:

bash
sudo cp config/secrets.env.example /etc/orchestra/secrets.env
sudo chmod 0600 /etc/orchestra/secrets.env
sudo $EDITOR /etc/orchestra/secrets.env
sudo systemctl restart orchestra-listener orchestra-dispatcher

All keys are documented in the template. At minimum you need the Anthropic/ccr keys and the GitHub App credentials; Linear, Slack, Sentry, and Langfuse are optional per the integrations you enable.

5. Integrations ​

Each integration is wired via webhook (HMAC-verified) + secrets. See ops.md § Ingestion for the exact endpoint, signature header, dedup key, and payload contract per source.

  • GitHub App — install on your org (PR read/write, contents read, checks read). Point its webhook at https://<your-fqdn>/webhook/github. Use a separate bot account as the review target (GITHUB_BOT_USERNAME) to avoid a self-review loop.
  • Linear (optional) — webhook → /webhook/linear; set LINEAR_BOT_USER_ID so only assign-to-bot events dispatch.
  • Slack (optional) — Events API → /webhook/slack; only app_mention is handled.
  • Sentry / Langfuse (optional) — /webhook/sentry, /webhook/langfuse.

6. Operate & verify ​

bash
orchestra tui                               # dashboard: sessions, human tasks, timers, logs
curl http://127.0.0.1:3000/health           # 200 + 4-table schema check
curl http://127.0.0.1:3000/metrics          # latency percentiles + error rates
journalctl -u orchestra-dispatcher -f       # dispatcher activity

Smoke-check the pipeline end to end by assigning a Linear issue to the bot (or @-mentioning it on a GitHub PR) and watching the task flow through the TUI: pending → running → done.

Deploy updates ​

  • Laptop → VM: git push origin main then ORCHESTRA_VM=user@host orchestra deploy.
  • On the VM (operator): edit, commit, then sudo /opt/orchestra/scripts/apply-local.sh.
  • By the builder agent: approved proposals deploy via apply-local-by-agent.sh under a lock, with post-deploy health checks and auto-rollback. See ops.md § Deploy.

Only orchestra-listener and orchestra-dispatcher restart on deploy; ccr is left running to avoid killing in-flight LLM connections.