Orchestra 0.12.1

Orchestra

Deterministic AI agent orchestrations. Describe a workflow as a declarative DAG of steps in a single JSON/YAML file, and Orchestra runs it — resolving dependencies, streaming progress, and driving each Prompt step on a real coding agent (GitHub Copilot or OpenCode). It ships as one self-contained command-line tool with a built-in web portal, a one-shot runner, MCP integration, triggers, checkpointing, and human-in-the-loop pauses.

inputs ─▶ ┌─ research ─┐                       orchestra init
          │            ├─▶ brief ─▶ document   orchestra doctor
          └─ (Copilot) ─┘         (no model)   orchestra run hello

Highlights

• Zero to running in two commands. orchestra init scaffolds a working workspace; orchestra doctor verifies your machine before the first run instead of failing mid-run.
• One file, one DAG. Steps (Prompt, Command, Script, Http, Transform, Approval, nested Orchestration) wired by dependsOn, with template expressions ({{param.x}}, {{step.output}}).
• Pluggable agents. Run any Prompt step on copilot or opencode, selectable per step or per orchestration.
• MCP-native. Attach Model Context Protocol servers to steps, and expose your orchestrations as an MCP server.
• Agent Skills. Drop SKILL.md directories onto a step so the agent gains specialized, on-demand workflows.
• Live agent plans. Inspect read-only task progress, plan documents, and durable revision history during or after execution. See agent plans.
• Structured results and bounded autopilot. Set responseSchema for validated JSON and opt into executionPolicy.mode: autopilot for bounded continuation within a step. See provider contracts.
• Operate it. A web portal, triggers (cron/webhook/file/manual), durable checkpoint/resume, profiles & tags, and a full CLI — all under the single orchestra command.

Install

Orchestra is distributed as the Orchestra command-line tool (command: orchestra) on NuGet. Your orchestrations are just JSON/YAML — no C# required.

# Run without installing (recommended for trying it out) — requires the `dnx` launcher:
dnx Orchestra --yes -- <command> [options]

# …or install it as a global tool:
dotnet tool install --global Orchestra
orchestra <command> [options]

Running orchestra with no command prints the help. orchestra <command> --help documents any subcommand.

Quick start

orchestra init             # scaffold a workspace with a runnable example
orchestra doctor           # verify prerequisites before the first run
orchestra run hello        # run it
orchestra new my-workflow  # then add your own, from a template

No agent set up yet? orchestra init --template smoke-test --yes && orchestra run smoke-test gives you a green run in about a second with nothing configured - it proves the install before credentials enter the picture.

init writes a starter orchestration under orchestrations/, the JSON schemas under .orchestra/schemas/ for editor autocomplete, and an orchestra.json whose scan block is what lets you run orchestrations by name. It prompts for the template, provider, and model — pass any of those as flags to skip the prompt, or --yes to accept every default:

orchestra init ./my-workflows --template research --provider copilot --yes

Five templates ship with the tool, and every one runs with no arguments:

doctor checks the things that otherwise only fail during a run: which orchestra.json is in effect and whether it parses, whether the data path is writable, whether the agent CLI is present and authenticated, and whether a configured server is reachable. The first Copilot run downloads the Copilot CLI (~100 MB, once per machine) — orchestra doctor --fix does it up front instead of mid-run. If credentials are missing, orchestra login runs the provider's own sign-in flow.

Orchestra discovers orchestra.json by walking up from your working directory, so a scaffolded folder is self-contained; a user-global config at %APPDATA%\Orchestra\ (or ~/.config/Orchestra/) applies everywhere else.

validate parses an orchestration and checks its expressions without a server, an agent, or any cost — it exits 0/1/2 so CI and Script steps can branch on it:

orchestra validate ./orchestrations/hello.yaml                  # parser + template checks
orchestra validate ./orchestrations/hello.yaml --schema         # + JSON Schema: typos, bad values
orchestra run --run-file ./orchestrations/hello.yaml --dry-run  # print the layered plan, run nothing

Your first orchestration

orchestra init writes this for you as orchestrations/hello.yaml; here it is in full. It's a DAG: research produces findings, brief summarizes them, and document shapes the result without calling a model at all.

# yaml-language-server: $schema=../.orchestra/schemas/orchestration.schema.json
name: hello
description: Research a topic, brief it, then assemble a document.
defaultModel: claude-opus-4.8

inputs:
  topic:
    type: string
    required: false
    default: deterministic AI agent orchestration

steps:
  - name: research
    type: Prompt
    systemPrompt: You are a meticulous research assistant.
    userPrompt: Research "{{param.topic}}" and list the key findings as concise bullet points.

  - name: brief
    type: Prompt
    dependsOn: [research]
    systemPrompt: You are a technical writer.
    userPrompt: |
      Using the research below, write a 120-word executive brief on {{param.topic}}.

      {{research.output}}

  - name: document
    type: Transform
    dependsOn: [brief]
    template: |
      # {{param.topic}}

      {{brief.output}}

Because topic has a default, orchestra run hello works with no arguments — and --param topic="vector databases" points it somewhere else.

Run it

orchestra run runs one orchestration to completion. With dnx (no install):

dnx Orchestra --yes -- run --run-file ./orchestrations/hello.yaml --param topic="vector databases" --report markdown

--mode decides where it runs:

• auto (default) — attach to a running Orchestra instance when one is configured (via --server, the ORCHESTRA_URL env var, or the hostBaseUrl/urls in your discovered orchestra.json) and healthy; otherwise spawn a throwaway in-process host just for this run.
• existing — require a healthy configured instance (error if none).
• isolated — always run self-contained. orchestra exec is shorthand for run --mode isolated.

orchestra run hello --param topic="vector databases"   # registered, on your server (auto)
orchestra exec --run-file ./orchestrations/hello.yaml  # self-contained one-shot
orchestra portal --open                                # long-running host + web UI, opens the browser
orchestra config show                                  # which orchestra.json is in effect, and why

The portal (orchestra portal) serves the dashboard, REST API, and MCP endpoints; the client verbs (orchestra list, get, register, attach, runs, triggers, profiles, tags, pending, respond, …) talk to it over HTTP/SSE.

Step types

Agent providers

Starting with 0.11, Prompt, Command, and Script steps default to the orchestration file's directory. Use workingDirectory: ".." for a definition stored one level below its project root. OpenCode steps require V2. The bundled authoring skill documents the new provider controls and migration rules.

Every Prompt step runs on an agent provider, chosen by precedence step provider → orchestration defaultProvider → host default:

defaultProvider: opencode
steps:
  - name: draft   # runs on OpenCode (the orchestration default)
    type: Prompt
    userPrompt: "..."
  - name: review
    type: Prompt
    provider: copilot   # this step overrides to Copilot
    userPrompt: "..."

• copilot — GitHub Copilot's agent runtime via the Copilot SDK. See the CLI parity investigation for tested capabilities and configuration differences.
• opencode — uses the OpenCode V2 HTTP API; supports MCPs, subagents, model variants, explicit skills/instructions, engine tools, attachments, native questions, permissions, validated JSON, and Orchestra-managed bounded continuation.

The engine fails a step fast if it uses a feature the chosen provider doesn't support (rather than silently dropping it). See docs/copilot.md and the provider notes for the full capability matrix.

Agent Skills

Agent Skills are SKILL.md directories that give a Prompt step specialized, discover-on-demand knowledge and workflows. Reference them per step with skillDirectories (relative paths resolve from the orchestration file):

steps:
  - name: code-review
    type: Prompt
    skillDirectories:
      - ./skills/code-review
      - ./skills/security-analysis
    userPrompt: "Review these changes: {{param.changes}}"

A SKILL.md is Markdown with a small YAML frontmatter (name, description) plus the instructions and any reference files. Orchestra ships an orchestration-authoring skill (under skills/) that teaches an agent to write valid Orchestra files. It ships inside the tool too, so orchestra init --with-skill drops a copy into .orchestra/skills/ without cloning this repo — that's what the generate template uses to write orchestrations from a plain-English description:

orchestra init --template generate
orchestra run generate --param description="review my open PRs every morning and post a digest"

The generated file is machine-checked with orchestra validate before it's written, so a draft that wouldn't parse fails the run instead of landing on disk.

MCP integration

Attach Model Context Protocol servers (local stdio or remote HTTP) to a step so the agent gains tools:

mcps:
  - name: zakira-recall
    type: local
    command: dnx
    arguments: ["Zakira.Recall", "--yes", "--", "mcp"]
steps:
  - name: research
    type: Prompt
    mcps: [zakira-recall]
    userPrompt: "Use the web tools to research {{param.topic}} and summarize."

Orchestra also exposes your orchestrations as an MCP server (/mcp/data), so other agents can discover and invoke them. See docs/host.md.

Documentation

License

MIT — see LICENSE. Repository: https://github.com/MoaidHathot/Orchestra.